Hub Listing - Request and Response Transformations (Definitions 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 Gateway tab

Request and response transformations can also be configured using the Gateway 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 > Definitions tab for the API you want to edit. Click Endpoints, then click Edit for an endpoint in which you want to manage transformations. (You can also do this more generally for an API using the Gateway tab.)

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

Defining a transformation

Step 1: Select either Request Transformations or Response Transformations

Step 2: Select an action

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

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: Define the target

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

Transformations work on the following targets:

• 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.
• Query parameter - For example, to add a myParameter query parameter to the request string, the target would be request.query.myParameter.
• Form field - For example, to add a myFormField form field to the HTML form in the request, the target would be request.form.myFormField.

Step 4: Select a type and value

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. You have the option to Overwrite if exists, which will always use the value from the transformation, or Ignore if exists, which will use the value that the API consumer specified.

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.