redirect.md

title	keywords	description
redirect	Apache APISIX API Gateway Plugin Redirect	This document contains information about the Apache APISIX redirect Plugin.

Description

The redirect Plugin can be used to configure redirects.

Attributes

Name	Type	Required	Default	Valid values	Description
http_to_https	boolean	False	false		When set to true and the request is HTTP, it will be redirected to HTTPS with the same URI with a 301 status code. Note the querystring from the raw URI will also be contained in the Location header.
uri	string	False			URI to redirect to. Can contain Nginx variables. For example, /test/index.html, $uri/index.html, ${uri}/index.html, https://example.com/foo/bar. If you refer to a variable name that doesn't exist, instead of throwing an error, it will treat it as an empty variable.
regex_uri	array[string]	False			Match the URL from client with a regular expression and redirect. If it doesn't match, the request will be forwarded to the Upstream. Only either of uri or regex_uri can be used at a time. For example, [" ^/iresty/(.)/(.)/(.*)", "/$1-$2-$3"], where the first element is the regular expression to match and the second element is the URI to redirect to. APISIX only support one regex_uri currently, so the length of the regex_uri array is 2.
ret_code	integer	False	302	[200, ...]	HTTP response code.
encode_uri	boolean	False	false		When set to true the URI in the Location header will be encoded as per RFC3986.
append_query_string	boolean	False	false		When set to true, adds the query string from the original request to the Location header. If the configured uri or regex_uri already contains a query string, the query string from the request will be appended to it with an &. Do not use this if you have already handled the query string (for example, with an Nginx variable $request_uri) to avoid duplicates.

:::note

• Only one of http_to_https, uri and regex_uri can be configured.
• Only one of http_to_https and append_query_string can be configured.
• When enabling http_to_https, the ports in the redirect URL will pick a value in the following order (in descending order of priority)
  • Read plugin_attr.redirect.https_port from the configuration file (conf/config.yaml).
  • If apisix.ssl is enabled, read apisix.ssl.listen and select a port randomly from it.
  • Use 443 as the default https port.

:::

Enabling the Plugin

The example below shows how you can enable the redirect Plugin on a specific Route:

curl http://127.0.0.1:9180/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri": "/test/index.html",
    "plugins": {
        "redirect": {
            "uri": "/test/default.html",
            "ret_code": 301
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:80": 1
        }
    }
}'

You can also use any built-in Nginx variables in the new URI:

curl http://127.0.0.1:9180/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri": "/test",
    "plugins": {
        "redirect": {
            "uri": "$uri/index.html",
            "ret_code": 301
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:80": 1
        }
    }
}'

Example usage

First, we configure the Plugin as mentioned above. We can then make a request and it will be redirected as shown below:

curl http://127.0.0.1:9080/test/index.html -i

HTTP/1.1 301 Moved Permanently
Date: Wed, 23 Oct 2019 13:48:23 GMT
Content-Type: text/html
Content-Length: 166
Connection: keep-alive
Location: /test/default.html
...

The response shows the response code and the Location header implying that the Plugin is in effect.

The example below shows how you can redirect HTTP to HTTPS:

curl http://127.0.0.1:9180/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri": "/hello",
    "plugins": {
        "redirect": {
            "http_to_https": true
        }
    }
}'

To test this:

curl http://127.0.0.1:9080/hello -i

HTTP/1.1 301 Moved Permanently
...
Location: https://127.0.0.1:9443/hello
...

Disable Plugin

To disable the redirect Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.

curl http://127.0.0.1:9180/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri": "/test/index.html",
    "plugins": {},
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:80": 1
        }
    }
}'