Skip to main content

Redirect

The redirect plugin can return an HTTP redirect from a route or service before the request reaches the upstream. It can move clients from an old path to a new endpoint, build destinations from request variables or regular-expression captures, and redirect HTTP traffic to HTTPS.

Request Handling​

Configure exactly one redirect mode:

ModeBehavior
uriRedirects every matching request to a fixed or variable-based destination.
regex_uriRewrites the request path with a regular expression and redirects only when the expression matches. A request that does not match continues to the upstream service.
http_to_httpsRedirects an HTTP request to the same host and request URI over HTTPS.

Fixed and regular-expression redirects use the configured response code, with 302 as the default. A request continues to the upstream when its regular expression does not match. Automatic HTTP-to-HTTPS redirects use 301 for GET and HEAD requests and 308 for other methods; requests already using HTTPS also continue to the upstream.

Examples​

The examples first configure a regex-based permanent redirect that preserves the original query string. The second example redirects HTTP requests to the same host and request URI over HTTPS.

Redirect a Legacy Path​

The route maps /legacy/<path> to /v2/<path>. The gateway returns the redirect directly, so the configured upstream is not contacted when the regular expression matches.

Create and enter a working directory for the example:

mkdir redirect-example
cd redirect-example

If Admin API authentication is enabled, export an admin-role key as ADMIN_API_KEY before using the Admin API tab.

Create the route:

curl "http://127.0.0.1:9180/apisix/admin/routes/redirect-legacy-route" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"uri": "/legacy/*",
"plugins": {
"redirect": {
"regex_uri": ["^/legacy/(.*)", "/v2/$1"],
"ret_code": 308,
"append_query_string": true
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'

Send a request to the legacy path:

curl --head "http://127.0.0.1:9080/legacy/orders?source=docs"

The response should use 308 Permanent Redirect and preserve the captured path and query string in Location:

HTTP/1.1 308 Permanent Redirect
Location: /v2/orders?source=docs

Redirect HTTP to HTTPS​

Create a second route that redirects HTTP requests to the same host and request URI over HTTPS:

curl "http://127.0.0.1:9180/apisix/admin/routes/redirect-https-route" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"uri": "/secure",
"plugins": {
"redirect": {
"http_to_https": true
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'

Send an HTTP request with a representative host name:

curl --silent --head "http://127.0.0.1:9080/secure" \
-H "Host: api.example.com" | \
grep -E "^(HTTP/|Location:)"

The response is a permanent redirect to HTTPS for the same host and path:

HTTP/1.1 301 Moved Permanently
Location: https://api.example.com:9443/secure

The response redirects to HTTPS on the selected non-default port. Port 443 would be omitted because HTTPS implies it.