Description

The response-rewrite Plugin rewrites the content returned by the Upstream and APISIX.

This Plugin can be useful in these scenarios:

• To set Access-Control-Allow-* field for supporting CORS.
• To set custom status_code and Location fields in the header to redirect.

:::tip

You can also use the redirect Plugin to setup redirects.

:::

Attributes

:::note

Only one of body or filters can be configured.

:::

Enabling the Plugin

The example below enables the response-rewrite Plugin on a specific Route:

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/test/index.html",
    "plugins": {
        "response-rewrite": {
            "body": "{\"code\":\"ok\",\"message\":\"new json body\"}",
            "headers": {
                "X-Server-id": 3,
                "X-Server-status": "on",
                "X-Server-balancer_addr": "$balancer_ip:$balancer_port"
            },
            "vars":[
                [ "status","==",200 ]
            ]
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:80": 1
        }
    }
}'

Here, vars is configured to run the Plugin only on responses with a 200 status code.

Example usage

Once you have enabled the Plugin as shown above, you can make a request:

curl -X GET -i  http://127.0.0.1:9080/test/index.html

The response will be as shown below no matter what the response is from the Upstream:

HTTP/1.1 200 OK
Date: Sat, 16 Nov 2019 09:15:12 GMT
Transfer-Encoding: chunked
Connection: keep-alive
X-Server-id: 3
X-Server-status: on
X-Server-balancer_addr: 127.0.0.1:80

{"code":"ok","message":"new json body"}

:::info IMPORTANT

ngx.exit will interrupt the execution of a request and returns its status code to Nginx.

However, if ngx.exit is executed during an access phase, it will only interrupt the request processing phase and the response phase will still continue to run.

So, if you have configured the response-rewrite Plugin, it do a force overwrite of the response.

:::

Disable Plugin

To disable the response-rewrite Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/test/index.html",
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:80": 1
        }
    }
}'