Rewrite Proxy Requests

The proxy-rewrite plugin allows you to modify the client request before it is sent to the upstream service. This is useful for tasks such as changing the URI path, overriding the HTTP method, or adding mandatory headers required by the backend.

Prerequisites

• An API7 Enterprise instance is running.
• A Gateway Group is created and a Gateway instance is running.
• A token from the Dashboard.

Rewrite a Static URI Path

You can replace the entire URI path of a request before it reaches the upstream. For example, rewriting /rewrite/get to /get.

Admin API

curl -k "https://localhost:7443/apisix/admin/services/proxy-rewrite-service?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "proxy-rewrite-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/static-rewrite-route?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "static-rewrite-route",
    "methods": ["GET"],
    "paths": ["/rewrite/get"],
    "service_id": "proxy-rewrite-service",
    "plugins": {
      "proxy-rewrite": {
        "uri": "/get"
      }
    }
  }'

ADC

adc.yaml

services:
  - name: proxy-rewrite-service
    upstream:
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
    routes:
      - name: static-rewrite-route
        uris:
          - /rewrite/get
        methods:
          - GET
        plugins:
          proxy-rewrite:
            uri: /get

adc sync -f adc.yaml

Rewrite Using Regular Expressions

Regex rewriting is more flexible and can be used to strip prefixes or transform parts of the path. For example, to strip the /rewrite-regex prefix so the upstream receives /get.

Admin API

curl -k "https://localhost:7443/apisix/admin/services/regex-rewrite-service?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "regex-rewrite-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/regex-rewrite-route?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "regex-rewrite-route",
    "methods": ["GET"],
    "paths": ["/rewrite-regex/*"],
    "service_id": "regex-rewrite-service",
    "plugins": {
      "proxy-rewrite": {
        "regex_uri": ["^/rewrite-regex/(.*)", "/$1"]
      }
    }
  }'

ADC

adc.yaml

services:
  - name: regex-rewrite-service
    upstream:
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
    routes:
      - name: regex-rewrite-route
        uris:
          - /rewrite-regex/*
        methods:
          - GET
        plugins:
          proxy-rewrite:
            regex_uri:
              - "^/rewrite-regex/(.*)"
              - "/$1"

adc sync -f adc.yaml

The regex_uri field takes an array of pairs: [pattern, replacement]. The first matching pattern in the array will be used for the rewrite.

Modify Request Headers

You can add, set, or remove headers before proxying to the upstream. This is commonly used for injecting authentication tokens or removing sensitive client-side headers.

Admin API

curl -k "https://localhost:7443/apisix/admin/services/header-rewrite-service?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "header-rewrite-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/header-rewrite-route?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "header-rewrite-route",
    "methods": ["GET"],
    "paths": ["/anything/headers-rewrite"],
    "service_id": "header-rewrite-service",
    "plugins": {
      "proxy-rewrite": {
        "headers": {
          "set": {
            "X-Internal-Token": "secret-value"
          },
          "add": {
            "X-Added-Header": "example"
          },
          "remove": ["User-Agent"]
        }
      }
    }
  }'

ADC

adc.yaml

services:
  - name: header-rewrite-service
    upstream:
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
    routes:
      - name: header-rewrite-route
        uris:
          - /anything/headers-rewrite
        methods:
          - GET
        plugins:
          proxy-rewrite:
            headers:
              set:
                X-Internal-Token: "secret-value"
              add:
                X-Added-Header: "example"
              remove:
                - "User-Agent"

adc sync -f adc.yaml

Header Actions

• set: Sets the header to a specified value, overwriting any existing value.
• add: Adds the header to the request without overwriting existing values.
• remove: Removes the specified header from the request.

Override HTTP Method

You can force a specific HTTP method for all upstream requests. For example, changing a PUT request to a POST request.

Admin API

curl -k "https://localhost:7443/apisix/admin/services/method-rewrite-service?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "method-rewrite-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/method-rewrite-route?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "method-rewrite-route",
    "paths": ["/anything/method-rewrite"],
    "service_id": "method-rewrite-service",
    "plugins": {
      "proxy-rewrite": {
        "method": "POST"
      }
    }
  }'

ADC

adc.yaml

services:
  - name: method-rewrite-service
    upstream:
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
    routes:
      - name: method-rewrite-route
        uris:
          - /anything/method-rewrite
        plugins:
          proxy-rewrite:
            method: POST

adc sync -f adc.yaml

Validate the Configuration

Send a request to the configured route and observe the response or inspect the upstream logs to verify the changes.

curl -i "http://127.0.0.1:9080/rewrite/get"

For the header rewrite example, you can inspect the upstream request headers returned by httpbin:

curl -s "http://127.0.0.1:9080/anything/headers-rewrite"

For the method rewrite example, send a PUT request and confirm the upstream sees POST:

curl -s -X PUT "http://127.0.0.1:9080/anything/method-rewrite"

If you configured the regex rewrite example, sending a request to http://127.0.0.1:9080/rewrite-regex/get should make the upstream receive /get.

If the route returns 404 immediately after you apply the configuration, wait a few seconds for the latest configuration to reach the gateway and retry.

Troubleshooting

• Regex Not Matching: Ensure your regex pattern is correct and covers the full URI path if needed. Test your regex with tools like pcregrep if you are using complex patterns.
• Header Conflicts: If multiple plugins modify the same header, the order of execution matters. Ensure proxy-rewrite is configured appropriately relative to other plugins.
• Invalid URI: The uri field must start with /. If you encounter a 400 Bad Request during configuration, verify the uri syntax.

Next Steps

• Implement Traffic Splitting — route a percentage of traffic to new versions.
• Configure Rate Limiting — protect your services from traffic spikes.