a7-plugin-proxy-rewrite

Overview

The proxy-rewrite plugin rewrites request attributes before API7 EE forwards the request to the upstream. You can change the URI path, host header, HTTP method, scheme, and add/set/remove request headers — all without modifying your backend service.

When to Use

• Rewrite the URI path before forwarding (e.g., strip a prefix like /api/v1)
• Rewrite the Host header for backend routing
• Change the HTTP method (e.g., convert POST to PUT)
• Add, set, or remove request headers before proxying
• Use regex-based URI rewriting for complex path transformations
• Switch the scheme from HTTP to HTTPS (or vice versa) when proxying

Plugin Configuration Reference (Route/Service)

Field	Type	Required	Default	Description
uri	string	No	—	New upstream request URI. Supports Nginx variables (e.g., $uri, $arg_name).
method	string	No	—	Override the HTTP method. Must be uppercase: GET, POST, PUT, DELETE, etc.
host	string	No	—	New Host header value sent to upstream.
scheme	string	No	—	New scheme for upstream request: http or https.
headers	object	No	—	Header manipulation object with set, add, and remove fields.
headers.set	object	No	—	Set (overwrite) headers. Key-value pairs. Supports Nginx variables.
headers.add	object	No	—	Append headers. Key-value pairs. Adds even if the header already exists.
headers.remove	array[string]	No	—	Remove headers. List of header names to strip.
regex_uri	array[string]	No	—	Array of two strings: [pattern, replacement]. Uses PCRE regex to rewrite the URI.
use_real_request_uri_unsafe	boolean	No	false	Use the original unescaped URI. Security risk — only enable if you understand the implications.

Priority: If both uri and regex_uri are set, uri takes precedence.

Step-by-Step: Enable proxy-rewrite on a Route

1. Simple URI rewrite (strip prefix)

Strip /api/v1 prefix so /api/v1/users becomes /users for gateway group default:

a7 service create --gateway-group default -f - <<'EOF'
{
  "id": "proxy-rewrite-backend",
  "name": "proxy-rewrite-backend",
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "strip-prefix",
  "uri": "/api/v1/*",
  "service_id": "proxy-rewrite-backend",
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["^/api/v1/(.*)", "/$1"]
    }
  }
}
EOF

2. Rewrite host header

Route to a different virtual host on the backend:

a7 service create --gateway-group prod -f - <<'EOF'
{
  "id": "legacy-backend-service",
  "name": "legacy-backend-service",
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

a7 route create --gateway-group prod -f - <<'EOF'
{
  "id": "rewrite-host",
  "uri": "/legacy/*",
  "service_id": "legacy-backend-service",
  "plugins": {
    "proxy-rewrite": {
      "host": "legacy.internal.svc"
    }
  }
}
EOF

3. Add and remove headers

a7 service create --gateway-group stage -f - <<'EOF'
{
  "id": "header-backend-service",
  "name": "header-backend-service",
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

a7 route create --gateway-group stage -f - <<'EOF'
{
  "id": "header-manip",
  "uri": "/api/*",
  "service_id": "header-backend-service",
  "plugins": {
    "proxy-rewrite": {
      "headers": {
        "set": {
          "X-Forwarded-Proto": "https",
          "X-Real-IP": "$remote_addr"
        },
        "add": {
          "X-Request-Start": "$msec"
        },
        "remove": ["X-Internal-Debug", "X-Secret-Token"]
      }
    }
  }
}
EOF

Common Patterns

Regex URI rewrite with capture groups

Rewrite /products/123/reviews to /api/products?id=123&section=reviews:

{
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["^/products/(\\d+)/(.*)$", "/api/products?id=$1&section=$2"]
    }
  }
}

Change HTTP method

Convert GET to POST for a legacy backend:

{
  "plugins": {
    "proxy-rewrite": {
      "method": "POST"
    }
  }
}

Static URI replacement

Replace the entire URI path:

{
  "plugins": {
    "proxy-rewrite": {
      "uri": "/internal/health"
    }
  }
}

Use Nginx variables in URI

{
  "plugins": {
    "proxy-rewrite": {
      "uri": "/api/$arg_version/resource"
    }
  }
}

Combine URI rewrite with header manipulation

{
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["^/v2/(.*)", "/v3/$1"],
      "headers": {
        "set": {
          "X-API-Version": "v3"
        }
      }
    }
  }
}

Troubleshooting

Symptom	Cause	Fix
URI not rewritten	Both uri and regex_uri set — uri wins	Remove uri if you need regex
Regex not matching	Bad pattern or unescaped characters	Test regex with PCRE syntax; escape backslashes in JSON: \\d+
Nginx variable not resolved	Variable name typo or not available	Check Nginx variable list
404 after rewrite	Rewritten URI doesn't match upstream paths	Verify the rewritten path exists on the backend
Host header unchanged	host field not set or overridden by upstream	Explicitly set host in proxy-rewrite config
Header appears twice	Used set vs add confusion	Use set to overwrite, add to append
Config not applied	Wrong gateway group specified	Ensure --gateway-group matches the desired cluster

Config Sync Example

version: "1"
services:
  - id: proxy-rewrite-backend
    name: proxy-rewrite-backend
    upstream:
      type: roundrobin
      nodes:
        - host: backend
          port: 8080
          weight: 1
routes:
  - id: api-rewrite
    uri: /api/v1/*
    service_id: proxy-rewrite-backend
    plugins:
      proxy-rewrite:
        regex_uri:
          - "^/api/v1/(.*)"
          - "/$1"
        headers:
          set:
            X-Forwarded-Prefix: "/api/v1"
          remove:
            - X-Debug

---

This page is generated from a7-plugin-proxy-rewrite/SKILL.md in the api7/a7 repository. Browse all skills on the AI Agent Skills page.