Hub Listing - Request and Response Transformations (Gateway Tab)
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 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
Function | Description | Example use case |
---|---|---|
ADD | Add 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). |
REMAP | Remap 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. |
REMOVE | Remove 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 > 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 berequest.header.my-header
. - Body - For example, to add a
myField
field to a JSON request body, the target would berequest.body.myField
. - Form field - For example, to add a
myFormField
form field to the HTML form in the request, the target would berequest.form.myFormField
. - Query parameter - For example, to add a
myParameter
query parameter to the request string, the target would berequest.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 torequest.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.
ExampleThe 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.
Updated 10 months ago