Skip to main content

Request Transformer Advanced

Overview​

The Request Transformer Advanced policy allows API requests to be modified dynamically before reaching the backend. This policy provides transformation capabilities through five tag operations, ensuring requests conform to desired structures:

  • Remove Tag: Deletes specific headers, query parameters, or body fields.
  • Rename Tag: Changes the name of a field while preserving its value.
  • Replace Tag: Modifies existing values using templates, strings, or functions.
  • Add Tag: Introduces new fields in headers, query parameters, or the body.
  • Append Tag: Adds data to existing fields instead of replacing them.

This policy is particularly useful for structuring, securing, and optimizing API requests before forwarding them to the backend.

Configuration Details​

Parameter configuration​

Upon adding a tag, user can use these templates as values:

You can use any of the current request headers, query parameters, and captured URI groups as templates to populate supported configuration fields.

  • Request Parameter: header
  • Template: 
$(headers.<header_name>), $(headers["<Header-Name>"]) or $(headers["<header-name>"])
  • Request Parameter: query string
  • Template: 
$(query_params.<query-param-name>) or $(query_params["<query-param-name>"])
  • Request Parameter: captured URIs
  • Template: 
$(uri_captures.<group-name>) or $(uri_captures["<group-name>"])
  • Request Parameter: shared variables
  • Template: 
$(shared.<variable-name>) or $(shared["<variable-name>"])

To escape a template, wrap it inside quotes and pass inside another template. For example:

$('$(something_that_needs_to_escaped)')

Note: The plugin creates a non-mutable table of request headers, query strings, and captured URIs before transformation. Therefore, any update or removal of parameters used in a template does not affect the rendered value of a template.

A complete Lambda example for prefixing a header value with “Basic” if not already there:

Authorization:$((function()
    local value = headers.Authorization
    if not value then
      return
    end
    if value:sub(1, 6) == "Basic " then
      return value            -- was already properly formed
    end
    return "Basic " .. value  -- added proper prefix
  end)())

Note: Especially in multi-line templates like the example above, make sure not to add any trailing white space or new lines. Because these would be outside the placeholders, they would be considered part of the template, and hence would be appended to the generated value. The environment is sandboxed, meaning that Lambdas will not have access to any library functions, except for the string methods (like sub() in the example above).

Add "Remove" Tag​

  • Function: Removes a field from the request.
  • Configuration Steps:
    • Select "Remove" from the dropdown.
    • Enter the field name to delete.
    • Select the applicable scope (Headers, Query String, Body).
    • Click Save to apply the tag.

Add "Rename" Tag​

  • Function: Renames an existing request field while keeping its value unchanged.
  • Configuration Steps:
    • Select "Rename" from the dropdown.
    • Enter the current field name and new name.
    • Select the applicable scope (Headers, Query String, Body).
    • Click Save to apply the tag.

Add "Replace" Tag​

  • Function: Changes the value of an existing field using templates, strings, or functions.
  • Configuration Steps:
    • Select "Replace" from the dropdown.
    • Enter the field name for replacement.
    • Choose the new value type (Template, String, Function).
    • Enter the replacement value.
    • Select the applicable scope (Headers, Query String, Body).
    • Click Save to apply the tag.

Add "Add" Tag​

  • Function: Inserts a new field into the request.
  • Configuration Steps:
    • Select "Add" from the dropdown.
    • Enter the field name and new value.
    • Select the data type: Template – Uses predefined placeholders; String – Static text; Function – Dynamic logic-based values.
    • Choose the applicable scope (Headers, Query String, Body).
    • Click Save to apply the tag.

Add "Append" Tag​

  • Function: Appends additional data to an existing field rather than replacing it.
  • Configuration Steps:
    • Select "Append" from the dropdown.
    • Enter the field name and data to append.
    • Choose the data type (Template, String, Function).
    • Select the applicable scope (Headers, Query String, Body).
    • Click Save to apply the tag.

Update Tag​

  • Function: Allows modification of an existing tag.
  • Configuration Steps:
    • Click on a tag in the tag table.
    • The update popup appears with current tag details.
    • Modify the necessary values (e.g., field name, new value, data type).
    • Click Save to apply the changes.
    • Redeploy the API to ensure the changes take effect.

Delete Tag​

  • Function: Removes an existing tag from the policy configuration.
  • Configuration Steps:
    • Locate the tag in the tag table.
    • Click the (x) icon next to the tag name.
    • A confirmation popup appears.
    • Click Check to confirm deletion.
    • Redeploy the API to finalize the deletion.