Skip to main content

proxy-rewrite

The proxy-rewrite plugin offers options to rewrite requests that APISIX forwards to upstream services. With the plugin, you can modify the HTTP methods, request destination upstream addresses, request headers, and more.

Examples​

The examples below demonstrate how you can configure proxy-rewrite on a route in different scenarios.

Rewrite Host Header​

The following example demonstrates how you can modify the Host header in a request. Note that you should not use headers.set to set the Host header.

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "proxy-rewrite-route",
    "methods": ["GET"],
    "uri": "/headers",
    "plugins": {
      "proxy-rewrite": {
        "host": "myapisix.demo"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Send a request to /headers to check all the request headers sent to upstream:

curl "http://127.0.0.1:9080/headers"

You should see a response similar to the following:

{
  "headers": {
    "Accept": "*/*",
    "Host": "myapisix.demo", 
    "User-Agent": "curl/8.2.1", 
    "X-Amzn-Trace-Id": "Root=1-64fef198-29da0970383150175bd2d76d", 
    "X-Forwarded-Host": "127.0.0.1"
  }
}

Rewrite URI And Set Headers​

The following example demonstrates how you can rewrite the request upstream URI and set additional header values. If the same headers present in the client request, the corresponding header values set in the plugin will overwrite the values present in the client request.

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "proxy-rewrite-route",
    "methods": ["GET"],
    "uri": "/",
    "plugins": {
      "proxy-rewrite": {
        "uri": "/anything",
        "headers": {
          "set": {
            "X-Api-Version": "v1",
            "X-Api-Engine": "apisix"
          }
        }
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Send a request to verify:

curl "http://127.0.0.1:9080/" -H 'X-Api-Version: v2'

You should see a response similar to the following:

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*", 
    "Host": "httpbin.org", 
    "User-Agent": "curl/8.2.1", 
    "X-Amzn-Trace-Id": "Root=1-64fed73a-59cd3bd640d76ab16c97f1f1",
    "X-Api-Engine": "apisix", 
    "X-Api-Version": "v1",
    "X-Forwarded-Host": "127.0.0.1"
  },
  "json": null,
  "method": "GET",
  "origin": "::1, 103.248.35.179",
  "url": "http://localhost/anything"
}

Note that both headers are present, and the X-Api-Version value from the request is preserved with the plugin-configured value appended after it.

Rewrite URI And Append Headers​

The following example demonstrates how you can rewrite the request upstream URI and append additional header values. If the same headers present in the client request, their headers values will append to the configured header values in the plugin.

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "proxy-rewrite-route",
    "methods": ["GET"],
    "uri": "/",
    "plugins": {
      "proxy-rewrite": {
        "uri": "/headers",
        "headers": {
          "add": {
            "X-Api-Version": "v1",
            "X-Api-Engine": "apisix"
          }
        }
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Send a request to verify:

curl "http://127.0.0.1:9080/" -H 'X-Api-Version: v2'

You should see a response similar to the following:

{
  "headers": {
    "Accept": "*/*", 
    "Host": "httpbin.org", 
    "User-Agent": "curl/8.2.1", 
    "X-Amzn-Trace-Id": "Root=1-64fed73a-59cd3bd640d76ab16c97f1f1",
    "X-Api-Engine": "apisix", 
    "X-Api-Version": "v2,v1",
    "X-Forwarded-Host": "127.0.0.1"
  }
}

Note that both headers present and the header value of X-Api-Version passed in the request is preserved, with the plugin's configured value appended after it.

Remove Existing Header​

The following example demonstrates how you can remove an existing header User-Agent.

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "proxy-rewrite-route",
    "methods": ["GET"],
    "uri": "/headers",
    "plugins": {
      "proxy-rewrite": {
        "headers": {
          "remove":[
            "User-Agent"
          ]
        }
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Send a request to verify if the specified header is removed:

curl "http://127.0.0.1:9080/headers"

You should see a response similar to the following, where the User-Agent header is not present:

{
  "headers": {
    "Accept": "*/*", 
    "Host": "httpbin.org", 
    "X-Amzn-Trace-Id": "Root=1-64fef302-07f2b13e0eb006ba776ad91d", 
    "X-Forwarded-Host": "127.0.0.1"
  }
}

Rewrite URI Using RegEx​

The following example demonstrates how you can parse text from the original upstream URI path and use them to compose a new upstream URI path. In this example, APISIX is configured to forward all requests from /test/user/agent to /user-agent.

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "proxy-rewrite-route",
    "uri": "/test/*",
    "plugins": {
      "proxy-rewrite": {
        "regex_uri": ["^/test/(.*)/(.*)", "/$1-$2"]
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Send a request to /test/user/agent to check if it is redirected to /user-agent:

curl "http://127.0.0.1:9080/test/user/agent"

You should see a response similar to the following:

{
  "user-agent": "curl/8.2.1"
}

Add URL Parameters​

The following example demonstrates how you can add URL parameters to the request.

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "proxy-rewrite-route",
    "methods": ["GET"],
    "uri": "/get",
    "plugins": {
      "proxy-rewrite": {
        "uri": "/get?arg1=apisix&arg2=plugin"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Send a request to verify if the URL parameters are also forwarded to upstream:

curl "http://127.0.0.1:9080/get"

You should see a response similar to the following:

{
  "args": {
    "arg1": "apisix", 
    "arg2": "plugin"
  }, 
  "headers": {
    "Accept": "*/*", 
    "Host": "127.0.0.1", 
    "User-Agent": "curl/8.2.1", 
    "X-Amzn-Trace-Id": "Root=1-64fef6dc-2b0e09591db7353a275cdae4", 
    "X-Forwarded-Host": "127.0.0.1"
  }, 
  "origin": "127.0.0.1, 103.248.35.148",
  "url": "http://127.0.0.1/get?arg1=apisix&arg2=plugin"
}

Rewrite HTTP Method​

The following example demonstrates how you can rewrite a GET request into a POST request.

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "proxy-rewrite-route",
    "methods": ["GET"],
    "uri": "/get",
    "plugins": {
      "proxy-rewrite": {
        "uri": "/anything",
        "method":"POST"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Send a GET request to /get to verify if it is transformed into a POST request to /anything:

curl "http://127.0.0.1:9080/get"

You should see a response similar to the following:

{
  "args": {},
  "data": "", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Host": "127.0.0.1", 
    "User-Agent": "curl/8.2.1", 
    "X-Amzn-Trace-Id": "Root=1-64fef7de-0c63387645353998196317f2", 
    "X-Forwarded-Host": "127.0.0.1"
  }, 
  "json": null,
  "method": "POST",
  "origin": "::1, 103.248.35.179",
  "url": "http://localhost/anything"
}

Forward Consumer Names to Upstream​

The following example demonstrates how you can forward the name of consumers who authenticates successfully to upstream services. As an example, you will be using key-auth as the authentication method.

Create a consumer JohnDoe:

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "JohnDoe"
  }'

Create key-auth credential for the consumer:

curl "http://127.0.0.1:9180/apisix/admin/consumers/JohnDoe/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-john-key-auth",
    "plugins": {
      "key-auth": {
        "key": "john-key"
      }
    }
  }'

Next, create a route with key authentication enabled, and configure proxy-rewrite to add consumer name to the header:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "consumer-restricted-route",
    "uri": "/get",
    "plugins": {
      "key-auth": {},
      "proxy-rewrite": {
        "headers": {
          "set": {
            "X-Apisix-Consumer": "$consumer_name"
          },
          "remove": [ "Apikey" ]
        }
      }
    },
    "upstream" : {
      "nodes": {
        "httpbin.org":1
      }
    }
  }'

❶ Add the consumer name to the header X-Apisix-Consumer using the built-in variables.

❷ Remove the authentication key so that it is not visible to the upstream service.

Send a request to the route as consumer JohnDoe:

curl -i "http://127.0.0.1:9080/get" -H 'apikey: john-key'

You should receive an HTTP/1.1 200 OK response with the following body:

{
  "args": {}, 
  "headers": {
    "Accept": "*/*",
    "Host": "127.0.0.1", 
    "User-Agent": "curl/8.4.0", 
    "X-Amzn-Trace-Id": "Root=1-664b01a6-2163c0156ed4bff51d87d877",
    "X-Apisix-Consumer": "JohnDoe", 
    "X-Forwarded-Host": "127.0.0.1"
  }, 
  "origin": "172.19.0.1, 203.12.12.12", 
  "url": "http://127.0.0.1/get"
}
info

When using the Ingress Controller, the consumer name is prefixed with the namespace. For example, a consumer named JohnDoe in namespace aic will appear as aic_johndoe in the X-Apisix-Consumer header.

Send another request to the route without the valid credential:

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

You should receive an HTTP/1.1 401 Unauthorized response.

Dynamically Forward Requests in radixtree_uri_with_parameter Router Mode​

The following example demonstrates how to extract part of the URL path using the uri_param_* variable and forward the value to the upstream service in a new header. This example assumes that APISIX is operating in the radixtree_uri_with_parameter router mode.

Create a route as such:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "httpbin",
    "uri": "/anything/user/:user_id/profile",
    "plugins":{
      "proxy-rewrite": {
        "headers": {
          "set": {
            "X-User-ID": "$uri_param_user_id"
          }
        }
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

❶ Match requests to /anything/user/:user_id/profile where user_id is a parameter.

❷ Assign the user_id parameter value to a new header X-User-ID.

Send a request to the route:

curl "http://127.0.0.1:9080/anything/user/123/profile"

You should see the following response:

{
  "args": {}, 
  "data": "", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*",
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.6.0",
    "X-Amzn-Trace-Id": "Root=1-68873cf5-7248f64d19d607ea50aa9735",
    "X-Forwarded-Host": "127.0.0.1",
    "X-User-Id": "123"
  }, 
  ...
}

The route parameter can also accept URL-encoded string. For instance, if you send a request as such:

curl -i "http://127.0.0.1:9080/anything/user/123%20456/profile"

The user ID would be extracted as 123 456:

{
  "args": {}, 
  "data": "", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Host": "127.0.0.1", 
    "User-Agent": "curl/8.6.0",
    "X-Amzn-Trace-Id": "Root=1-68873d37-7634825b20d05dee3a852cb9",
    "X-Forwarded-Host": "127.0.0.1",
    "X-User-Id": "123 456"
  }, 
  ...
}
API7.ai Logo

The digital world is connected by APIs,
API7.ai exists to make APIs more efficient, reliable, and secure.

Sign up for API7 newsletter

Product

API7 Gateway
API7 AI Gateway
API7 API Portal

Learn

API Gateway Guide
Plugin Hub
API Gateway Comparison
Customers

Resources

API Gateway Docs
Blog
Demo Hub
APISIX vs Kong

Company

About
Contact
Compliance Standards
Partners
Terms & Privacy
SOC2 Type IIISO 27001HIPAAGDPRRed Herring

Copyright © APISEVEN PTE. LTD 2019 – 2026. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the Apache Software Foundation