redirect

Redirects requests to another URI or to HTTPS.

Category GeneralAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin redirectPriority 900

What it does

redirect answers a request itself instead of passing it on to your backend. The client receives a redirect status and a Location header naming the address to call instead. Its commonest job is HTTPS: with HTTP to HTTPS on, a request over plain HTTP is sent to the same host, path and query string over HTTPS, and a request that arrives over HTTPS passes untouched.

It knows only how the request reached the gateway. Behind a load balancer that ends HTTPS and sends the gateway plain HTTP, every request arrives that way. redirect then sends even a client that called over HTTPS back to HTTPS, again and again. There, send plain HTTP to HTTPS on the load balancer itself.

When to use it

• Clients that still call a route over plain HTTP, once the host answers HTTPS: they are sent to the HTTPS address.
• A path that moved: clients of the old path are sent to the new one, /v2/orders for example.
• A whole section of paths that moved, everything under /docs/ to /help/ for example, rewritten by one pattern.

Not for changing the path your backend receives without the client noticing — see proxy-rewrite (Rewrites the request URI, method, host and headers before proxying).

Guides

Pages that walk through a job with redirect, step by step.

• Send HTTP clients to HTTPSAnswer plain-HTTP requests with a redirect to the HTTPS address.

Set it up

Send plain HTTP requests to HTTPS

Add redirect once `https://api.example.com` answers. A client that calls `http://api.example.com` is then sent there.

Choose Redirect to HTTPS and turn on HTTP to HTTPS.

The console's Add plugin panel, filled with this example.

redirect · as the console saves it

{
  "http_to_https": true
}

What you will see

• A request over plain HTTP to api.example.com is answered 301 with Location: https://api.example.com:9443/orders/3201?page=2: the same host, path and query string over HTTPS, on the gateway's own HTTPS port.
• A POST over plain HTTP is answered 308 instead, with the same Location.
• A request that arrives over HTTPS passes untouched: over HTTPS to api.example.com it reaches your backend and is answered 200.
• A header X-Forwarded-Proto set to https changes nothing: a request that reaches the gateway over plain HTTP is still answered 301. Behind a load balancer that ends HTTPS and sends the gateway plain HTTP, a client that already called over HTTPS is therefore sent to HTTPS again.
• On a route that also carries key-auth, key-auth answers first: a request over plain HTTP without a key is answered 401 with {"message":"Missing API key in request"}, not redirected, and one with a valid key is answered 301.

More scenarios

Send clients to a new path permanently, keeping the method and the query string

Choose Redirect to a URI, set URI to /v2/orders, set Status code to 308 and turn on Append query string.

redirect · as the console saves it

{
  "uri": "/v2/orders",
  "ret_code": 308,
  "append_query_string": true
}

What you will see

• A POST to the old path with ?page=2 is answered 308 with Location: /v2/orders?page=2: the query string is kept.

Move a whole section of paths with one pattern

Choose Redirect by a pattern, fill Regex URI as in the JSON below and set Status code to 301.

redirect · as the console saves it

{
  "regex_uri": [
    "^/docs/(.*)",
    "/help/$1"
  ],
  "ret_code": 301
}

What you will see

• A request for /docs/intro is answered 301 with Location: /help/intro.

Things to know

• HTTP to HTTPS — The client is sent to the same host, path and query string over HTTPS, on the gateway's own HTTPS port: a request for /orders/3201?page=2 at api.example.com is sent to https://api.example.com:9443/orders/3201?page=2.
• HTTP to HTTPS — A header X-Forwarded-Proto set to https by a load balancer changes nothing: the gateway goes by how the request reached it, so behind a load balancer that ends HTTPS and sends the gateway plain HTTP, every request is redirected.
• Append query string — Turning it on beside HTTP to HTTPS is refused when you save: the HTTPS address already carries the query string.
• Status code — Only a 3xx moves the client: 200 answers with a Location header and an empty body, and 999 goes out as 999. With HTTP to HTTPS on, this is not read: GET and HEAD get 301, other methods 308.
• AdviceGive clients and their developers the https:// address from the start, and keep the redirect for those that still call plain HTTP. Add it to every route they may call that way.
• HTTP to HTTPS — Goes by how the request reached the gateway: behind a load balancer that ends HTTPS and sends plain HTTP, every request is redirected again and again, whatever X-Forwarded-Proto says. Redirect on the load balancer there.

Settings

The fields as the console shows them, section by section.

Choose one:

• Redirect to a URISend the client to an address written here.
• Redirect by a patternRead the requested address with a regular expression and build the new one from what it captured.
• Redirect to HTTPSSend the client back to the same host and address over https.

Redirect to a URI

URIuristringRequired

The address the client is sent to, such as /new-path or https://$host/new, where $name or ${name} takes that request variable. A name the request does not carry becomes empty. A backslash before the dollar stops the replacement but stays in the address: \$host is sent as \$host.

at least 2 characters ·

pattern

(\\\$[0-9a-zA-Z_]+)|\$\{([0-9a-zA-Z_]+)\}|\$([0-9a-zA-Z_]+)|(\$|[^$\\]+)

· example /new-path

Redirect by a pattern

Regex URIregex_uriarray of stringsRequired

Builds the redirect target from the client's path: the first part is the pattern to match, the second the template of the new path.

exactly 2 items

Redirect to HTTPS

HTTP to HTTPShttp_to_httpsbooleanRequired

Status coderet_codeintegerdefault 302

at least 200

Append query stringappend_query_stringbooleandefault false

Encode URIencode_uribooleandefault false

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.