Announcing request and response transformations in API gateway

Robert Wunderlich
Product Strategy Director

We’re pleased to announce the release of the request and response transformation policy in Oracle Cloud Infrastructure API Gateway! This policy supports the ability to transform headers and query strings between the API client and the backend service.

API management is all about unlocking the value of data and expanding your reach to partners but doing so in a secure and governed manner. When providing an API to your partners, it’s often based on an existing system backend, and that system might not always conform to the wanted experience for the client. 

The API gateway is a policy enforcement point that controls access to backend services. It also performs lightweight transformations where necessary.

A screenshot of the Create Deployment screen for transformations in Oracle Cloud Compute.


The request and response transformations have the following capabilities:

  • Mediate between frontend API clients and backend systems.

  • Inject authorization claims to control backend access.

  • Protect backends from receiving bad requests.

  • Redact sensitive information.

To better understand what this feature can do, let’s consider some use cases.

Filtering headers and query strings

When filtering, you can choose to block one or more headers or to allow only a specific list of headers.

A screenshot of the Request Header Transformations screen.

In a perfect world, the backend systems would fully support the requirements of the API clients, or mitigate any misbehavior. When exposing internal systems to external partners, it’s best to use the API gateway to ensure that only the allowed types of requests can pass.

The transformation policy provides filtering capabilities where you can block one or more headers or block all but a defined list of headers. This process ensures that your backend system receives only the type of requests that you intend.

For example, if someone tried to pass ?debug=1 to your backend to get it to reveal information, you can block this attempt with filtering.

Renaming headers and query strings

Sometimes, a backend system uses a header or query string that’s not user-friendly, or a request os routed to different backend systems based on the URL path. The API can have a common name and can rename headers and query strings to meet the needs of the backend systems.

Setting headers and query strings

Sometimes, a backend system needs to have a certain header or query parameter that frontend clients don’t provide. A legacy backend might not respond with the header that the client needs. The gateway ensures that the request and response meets the requirement with the following tasks:

  • Setting headers on the request or response. The gateway can use a static or dynamic value. When defining the value, you can reference other parts of the request.

    For example, a customer API is defined as .../customers/{customerID}, but the backend receives the customer id as a header named customer-id. The gateway can set header customer-id as ${request.path[customerID]}.

  • Setting query strings on the request are performed in the same manner. So, if the backend accepts customerID=1234 as a query string, the gateway can transform .../customers/1234 on the API client side to ?customerID=1234 on the backend.

  • When defining the transformation, you can define a rule on what action to take if the client provides the header: overwrite, skip, and append.

    For example, a backend service doesn’t handle a case if the Accept header is not passed, even though it should. The backend can’t be modified. The gateway can default the Accept header, so if the client passes the Accept header, it’s used and the gateway skips that rule. If not, the gateway goes ahead and sets it. The gateway can also append to a value passed in by the client. If you choose overwrite, the gateway sets the value in all cases.

The authorization context

The API gateway can validate JSON web tokens using the JSON Web Token Validator Policy. It also supports many token validations through Custom Authorizer Functions.

When an API is authorized, you can set an authorization context based on the claims in the token. All auth context elements are available to transform.

For example, if the authorization policy returns an auth context that includes tenant-id, and you want to route to your backend of /service/v1/${request.auth[tenant-id]}/customers, you can effectively support multitenant backends automatically from your authorization server to the API Gateway Authorization policy.

To learn more about how you can set the auth context, see Authentication and Authorization in API Deployments.

To learn more, visit our documentation on the request/response transformation policy!

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.