response-rewrite

Rewrites the response status, headers and body.

Category TransformationAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin response-rewritePriority 899

What it does

response-rewrite changes the answer the client gets from the route: its status under Status code, its headers under Headers, and its body. Body replaces the whole body, and Filters replace what a pattern matches inside it.

Body and Filters never go together in one configuration. A route that needs a fixed body takes the first, a route that corrects a few words of the backend's answer takes the second.

When to use it

• Every answer of the orders API must tell browsers and proxies not to keep a copy, with Cache-Control set to no-store.
• A header the backend adds about itself must not leave the gateway, removed under Remove.
• A backend that names an internal host in its answers, where clients must see the public name instead, rewritten under Filters.
• A route kept for old clients that answers with a fixed status and body while the backend behind it is retired.

Not for changing the request the backend receives, its path, Host or headers — see proxy-rewrite (Rewrites the request URI, method, host and headers before proxying) or answering with a made-up response and no backend at all — see mocking (Answers requests with a mocked response instead of an upstream).

Guides

Pages that walk through a job with response-rewrite, step by step.

• Set headers on every answerPut response-rewrite on a route to set, add or remove headers on every answer its clients get.

Set it up

Hide the gateway's Server header and forbid caching of every response

Choose Add, set and remove and fill Headers as in the JSON below.

The console's Add plugin panel, filled with this example.

response-rewrite · as the console saves it

{
  "headers": {
    "set": {
      "Cache-Control": "no-store"
    },
    "remove": [
      "Server"
    ]
  }
}

What you will see

• Every answer carries Cache-Control: no-store, whatever the backend sent.
• No Server header is among the answer's headers: the gateway removed the one it would have added.

Things to know

• Set — Set writes the header on the answer: with Cache-Control at no-store, a request to the route is answered 200 carrying Cache-Control with no-store.
• Add — An entry without a colon, noColonHere for example, is refused when you save.
• Body — A configuration that carries both Body and Filters is refused when you save.
• Body base64 — On, a Body that is not Base64, not base64!! for example, is refused when you save.
• Status code — A code from 200 to 598 is taken; 999 is refused when you save.
• Response body limit — Past this limit, the rest of what has arrived is dropped, and whatever the upstream sends after it passes unfiltered.
• AdviceTry a pattern under Filters against a real answer of the backend before you save it on a busy route.

Settings

The fields as the console shows them, section by section.

Status codestatus_codeinteger

The status code the response is sent with.

200 to 598

Bodybodystring

Replaces the response body with this text. Not stored beside Filters.

Body base64body_base64booleandefault false

Decodes the body from Base64 before it is sent, for binary content.

Choose one:

• One value per headerEvery header is written with the value given here, replacing what the response carries.
• Add, set and removeThree lists: headers to append, headers to write over and headers to drop.
• No header changes

One value per header

Headersheadersobject

Headers added to, set on or removed from the response. An object whose keys are a name without a colon, each with a string or number as its value.

Add, set and remove

Headersheadersobject

Headers added to, set on or removed from the response.

Addheaders.addarray of strings

One header per entry, written as Name: value, with no second colon.

at least 1 item

Removeheaders.removearray of strings

at least 1 item

Setheaders.setobject

An object whose keys are a name without a colon, each with a string or number as its value.

at least 1 key

Filtersfiltersarray of objects

Replacements made in the response body, each by a pattern and its substitute. Not stored beside Body.

at least 1 item

Each item:

Regexfilters[].regexstringRequired

The pattern matched in the response body.

at least 1 character

Replacefilters[].replacestringRequired

The text put in place of each match; it may refer to captured groups.

Optionsfilters[].optionsstringdefault jo

The regex options, such as case-insensitive matching.

Scopefilters[].scopestringdefault once

Whether the first match or every match in the body is replaced.

one of global, once

Varsvarsarray

example [["status","==",200]]

Response body limitmax_resp_body_sizeintegerdefault 67108864

Bytes of the response the filters read, 64 MiB unless set. Past this, the rest of what has arrived is dropped, and whatever the upstream sends after it passes unfiltered.

at least 1

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.