Hub Listing - Request and Response Transformations (Gateway Tab)

📘

Rapid Runtime only

This functionality uses the Rapid Runtime. If you are an Enterprise Hub customer and your API does not use the Rapid Runtime, this page does not apply.

📘

Also on the Definitions tab

Request and response transformations can also be configured using the Definitions tab. Once created, a transformation will appear on both the Gateway and Definitions tab.

Transformations allow you to add, remap, or remove headers, query parameters, bodies, and HTML form fields in API requests and responses. The API consumers using the API are not aware that the transformations are occurring, because the transformations occur when the requests reach the Rapid Runtime.

Transformation actions

📘

Adding a secret header or parameter vs. adding a request transformation

If you want the Rapid Runtime to add a secret name/value pair when a request is made by the API consumer, you have two similar choices. You can add a request transformation, as described below, or you can add a secret header or parameter, as described in Secret Headers and Parameters.

A secret header or parameter automatically applies to all endpoints and plans, always is set to a static value, and always overrides any existing value sent by the API consumer. Request transformations (as described below) are more flexible because they can apply to any number of the API's endpoints and plans, can have dynamic values, and conditions can be set on what to do if the header or parameter exists in the call from the API consumer.

In other words, because of their flexibility, using transformations is generally recommended over using secret headers and parameters.

Get started with transformations

To start, navigation to Studio (My APIs) and select the Hub Listing > Gateway tab for the API you want to edit. Scroll down to the Transformations section of the page (You can also work with transformations using the Definitions tab.)

This section allows you to remove, remap, or add headers, query parameters, bodies, and HTML form fields in API requests and responses.

Click Add transformation to begin the process of adding a request or response transformation.

Defining a transformation

Step 1: Select either Request or Response transformation

Step 2: Select an action

You can set the action to Add key, Remap key, or Remove key.

The remap action moves a value from a source to a target. For example, the following action removes the key1 field and value from the request body and add a newkey header to the request with the value from the key1 field.

Step 3: Select the key type

You can select from the available options, and add more detail (for example, the header name) using dot notation.

Transformations work on the following keys:

• Header - For example, to add a my-header header to a request, the target would be request.header.my-header.
• Body - For example, to add a myField field to a JSON request body, the target would be request.body.myField.
• Form field - For example, to add a myFormField form field to the HTML form in the request, the target would be request.form.myFormField.
• Query parameter - For example, to add a myParameter query parameter to the request string, the target would be request.query.myParameter.

Step 4: Select a value type

This step only applies to the add action. For the remap action, you would specify the source, as described in step 2 above.

You can select from Static, Variable, or Template.

• Select type Static for if you want to send plain text, JSON, or any fixed data.
• Select type Variable if you want to map the value from other parameters in the request. For example, setting the type to Variable and the value to request.header.x-rapidapi-host will copy the value from the existing header in the request to the new parameter defined in the Target.
• Select type Template if you want to read values from multiple variables and/or mix values and strings. You can use the mustache {{ }} syntax to insert variables.
  Example The value of the x-rapidapi-host header is {{request.header.x-rapidapi-host}}.

Step 5: Specify the condition

This step only applies to the add action.

The condition identifies what to do if the target parameter already exists in the API request sent by the consumer or response from the API gateway or hosting server. Checking the Overwrite value if exists box will always use the value from the transformation. If the box is unchecked and the key exists in the request or response, the value in the transformation will not be used.

Step 6: Set the scope of the transformation

Set the scope to include the full API or multi-select specific endpoints. To select multiple endpoints, hold down shift and click on an endpoint.

Step 7: Select which subscription plans are impacted

You can choose to apply the transformation to all of the plans or multi-select which specific plans it applies to. To select multiple plans, hold down shift and click on a plan.