# 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[​](#request-handling "Direct link to Request Handling")

Configure exactly one redirect mode:

| Mode            | Behavior                                                                                                                                                             |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uri`           | Redirects every matching request to a fixed or variable-based destination.                                                                                           |
| `regex_uri`     | Rewrites 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_https` | Redirects 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[​](#examples "Direct link to 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[​](#redirect-a-legacy-path "Direct link to 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.

* Admin API
* ADC

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

      }

    }

  }'
```

Configure ADC to connect to the target backend. The remaining ADC commands read the connection settings from these environment variables:

* APISIX
* API7 Gateway

If Admin API authentication is enabled, export an admin-role key as `ADMIN_API_KEY` before configuring ADC.

```
export ADC_BACKEND=apisix

export ADC_SERVER="http://127.0.0.1:9180"

export ADC_TOKEN="${ADMIN_API_KEY}"
```

```
export ADC_BACKEND=api7ee

export ADC_SERVER="https://{DASHBOARD_ADDR}"

export ADC_TOKEN="{DASHBOARD_TOKEN}"

export ADC_GATEWAY_GROUP="{GATEWAY_GROUP}"
```

Create the service and route:

adc.yaml

```
services:

  - name: redirect-service

    labels:

      docs-example: redirect

    routes:

      - name: redirect-legacy-route

        uris:

          - /legacy/*

        plugins:

          redirect:

            regex_uri:

              - ^/legacy/(.*)

              - /v2/$1

            ret_code: 308

            append_query_string: true

    upstream:

      type: roundrobin

      nodes:

        - host: httpbin.org

          port: 80

          weight: 1
```

Preview the changes and confirm that they only affect resources for this example:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=redirect
```

Review `diff.yaml`, then synchronize the labeled service:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=redirect
```

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[​](#redirect-http-to-https "Direct link to Redirect HTTP to HTTPS")

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

* Admin API
* ADC

```
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

      }

    }

  }'
```

In `adc.yaml`, add another route to the existing service:

adc.yaml (service routes)

```
routes:

  - name: redirect-https-route

    uris:

      - /secure

    plugins:

      redirect:

        http_to_https: true
```

Preview and synchronize the updated file:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=redirect



adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=redirect
```

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.
