# Rewrite Proxy Requests The [`proxy-rewrite`](https://docs.api7.ai/hub/proxy-rewrite.md) 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[​](#prerequisites "Direct link to Prerequisites") * An API7 Enterprise instance is running. * A Gateway Group is created and a Gateway instance is running. * A [token from the Dashboard](https://docs.api7.ai/api7-gateway/reference/obtain-dashboard-token.md). ## Rewrite a Static URI Path[​](#rewrite-a-static-uri-path "Direct link to 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 * ADC ``` curl -k "https://localhost:7443/apisix/admin/services/proxy-rewrite-service?gateway_group_id={gateway_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={gateway_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.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 labels: docs-example: proxy-rewrite-service ``` Preview the changes owned by this example and confirm that the diff contains no unintended updates or deletions: ``` adc diff -f adc.yaml \ --include-resource-type service \ --label-selector docs-example=proxy-rewrite-service ``` Synchronize the reviewed configuration: ``` adc sync -f adc.yaml \ --include-resource-type service \ --label-selector docs-example=proxy-rewrite-service ``` ## Rewrite Using Regular Expressions[​](#rewrite-using-regular-expressions "Direct link to 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 * ADC ``` curl -k "https://localhost:7443/apisix/admin/services/regex-rewrite-service?gateway_group_id={gateway_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={gateway_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.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" labels: docs-example: regex-rewrite-service ``` Preview the changes owned by this example and confirm that the diff contains no unintended updates or deletions: ``` adc diff -f adc.yaml \ --include-resource-type service \ --label-selector docs-example=regex-rewrite-service ``` Synchronize the reviewed configuration: ``` adc sync -f adc.yaml \ --include-resource-type service \ --label-selector docs-example=regex-rewrite-service ``` 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[​](#modify-request-headers "Direct link to 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 * ADC ``` curl -k "https://localhost:7443/apisix/admin/services/header-rewrite-service?gateway_group_id={gateway_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={gateway_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.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" labels: docs-example: header-rewrite-service ``` Preview the changes owned by this example and confirm that the diff contains no unintended updates or deletions: ``` adc diff -f adc.yaml \ --include-resource-type service \ --label-selector docs-example=header-rewrite-service ``` Synchronize the reviewed configuration: ``` adc sync -f adc.yaml \ --include-resource-type service \ --label-selector docs-example=header-rewrite-service ``` ### Header Actions[​](#header-actions "Direct link to 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[​](#override-http-method "Direct link to 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 * ADC ``` curl -k "https://localhost:7443/apisix/admin/services/method-rewrite-service?gateway_group_id={gateway_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={gateway_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.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 labels: docs-example: method-rewrite-service ``` Preview the changes owned by this example and confirm that the diff contains no unintended updates or deletions: ``` adc diff -f adc.yaml \ --include-resource-type service \ --label-selector docs-example=method-rewrite-service ``` Synchronize the reviewed configuration: ``` adc sync -f adc.yaml \ --include-resource-type service \ --label-selector docs-example=method-rewrite-service ``` ## Validate the Configuration[​](#validate-the-configuration "Direct link to 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[​](#troubleshooting "Direct link to 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[​](#next-steps "Direct link to Next Steps") * [Implement Traffic Splitting](https://docs.api7.ai/api7-gateway/how-to-guides/traffic-management/canary-release.md) — route a percentage of traffic to new versions. * [Configure Rate Limiting](https://docs.api7.ai/api7-gateway/how-to-guides/traffic-management/rate-limiting.md) — protect your services from traffic spikes.