4 mins READ

Modify API responses before they reach the client by adding, removing, renaming, or replacing headers and body fields.

Overview

A Response Transformer is an outbound policy that reshapes successful (200) API responses before they are returned to the client.

How it works

Response received from backend — The backend service returns a response to the gateway.
Policy evaluation — The policy applies only to successful (200) responses that match the configured protocols. Error responses are returned unchanged.
Transformation execution — Each rule is applied in sequence: headers or body fields are added, updated, renamed, replaced, or removed per the configured location.
Modified response returned — After all transformations, the updated response is sent to the client.

Attaching the policy

Policies can be attached to an access profile, an API, or an API group. They are applied in that order: access profile, then API, then API group.

Notes

Transformation rules are applied in the order you define them — if rules depend on each other (e.g., rename before replace), order them deliberately.
Use Remove to strip internal or sensitive fields (internal IDs, debug headers) before the response reaches clients.
Use Upsert to inject standard headers (e.g., X-API-Version) across all responses without changing every backend endpoint.
Test transformations against sample responses before attaching the policy to an API group, to confirm the output shape is what clients expect.

FAQs

Can I apply multiple transformation rules in a single policy?

Yes. A single Response Transformer Policy can contain multiple transformation rules, each targeting a different field or header. Rules are applied in the order they are defined.

What is the difference between Replace and Upsert?

Replace updates the value of an existing field and leaves it unchanged if the field does not exist. Upsert adds the field if it does not exist, or updates it if it does.

Can I transform the response body and headers in the same policy?

Yes. Each transformation rule specifies its own Location (Header or Body), so you can mix header and body transformations within a single policy.

Does the policy affect error responses from the backend?

No. The Response Transformer runs only on successful (200) responses. Error responses, including the fallback response and gateway errors such as 4xx and 5xx, are returned unchanged. To control the body of an error, use the API's error-code messages or its fallback response.

Last updated : 21 October 2026, 08:55 AM