Hub Listing - Request and Response Transformations

Transformations allow you to add, remap, or remove headers, query parameters, or bodies in API requests and API responses.

๐Ÿ“˜

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.

๐Ÿ“˜

This page includes the last section on content-type (removed from docs)

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

FunctionDescriptionExample use case
ADDAdd a header or parameter to an API request or response.Add a secret authentication parameter per plan in the case where each plan uses a different base URL (learn more about multi-base URLs here).
REMAPRemap a header or parameter in an API request or response.Remap a request authentication from query to header to provide a better developer experience, without modifying the original API.
REMOVERemove a header or parameter in an API request or response.Remove a parameter in the original API response so that it isn't displayed to the API consumer.

๐Ÿ“˜

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.)

Edit an endpoint in Studio to manage request and response transformations.

Editing an endpoint in Studio to manage request and response transformations.

This screen allows you to remove, remap, or add headers or parameters in API requests and responses.

Defining a transformation

Step 1: Select either Request Transformations or Response Transformations

Request and response transformations for an endpoint.

Request and response transformations for an endpoint.

Step 2: Select an action

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

2380

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.

Remapping a field in the body of the request to a new header.

Remapping a field in the body of the request to a new header.

Step 3: Define the target

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

2378

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}}.
Selecting a Variable value for the new 'docs' query parameter.

Selecting a Variable value for the new 'docs' query parameter.

2380

Setting a Static value for the new 'docs' query parameter.

Setting a Variable value for the new 'mysecret' header. It copies the existing value of the 'x-rapidapi-host' header.

Setting a Variable value for the new 'mysecret' header. It copies the existing value of the 'x-rapidapi-host' header.

Setting a Template value for the new 'mysecret' header.

Setting a Template value for the new 'mysecret' header.

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. 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.

Specifying what to do if the 'mysecret' header already exists in the API request.

Specifying what to do if the 'mysecret' header already exists in the API request.

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.

2376

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.

2380

How to add header "content-type" [Required if transforming methods]

While transforming methods, you must add the header content-type explicitly.

From the Edit Endpoint page, select the Headers tab. Add one of the following content-type headers to the Example Value field:

  • application/json
  • multipart/form-data
  • application/x-www-form-urlencoded
  • application/xml
  • text/plain
  • application/octet-stream

๐Ÿ“˜

Other content-type values

content-type values other than the list above are currently not supported.

1640

Save the changes once you are finished.