Request Transform Plugin

The Request Transform plugin is one of Crate’s most powerful features. It allows you to dynamically modify incoming requests and outgoing responses using the JSONata expression language.

⚙️ Configuration

The plugin can be enabled for Inbound (Request) and Outbound (Response) phases.

- urn: "urn:crate:plugin:request-transform"
  name: "dynamic-rewrite"
  type: "request_transform"
  active: true
  config:
    expression: |
      {
        "headers": {
          "set": {
            "X-Extracted-ID": $string(body.user_id),
            "X-Tenant": url.query.tenant_id
          },
          "remove": ["X-Internal-Secret"]
        },
        "url": {
          "path": "/v2/" & url.path
        }
      }

🏗️ Transformation Context

When your JSONata expression is evaluated, it has access to a rich Context Object that represents the current state of the transaction.

Inbound Context (Request)

Field	Description
`method`	HTTP method (e.g., `GET`, `POST`).
`url`	Object containing `path`, `host`, and `query` parameters.
`headers`	Map of all request headers.
`body`	The JSON request body (if `Content-Type: application/json`).
`params`	Route parameters extracted from the path (e.g., `id` from `/users/{id}`).
`target`	Details about the upstream destination (`host`, `path`, `raw`).

Outbound Context (Response)

Field	Description
`status`	The HTTP status code from the backend.
`headers`	Map of all response headers.
`body`	The JSON response body (if `Content-Type: application/json`).
`request`	The original request context (contains everything listed above).

🎨 Applying Transformations

Your JSONata expression should return an object that describes the changes to be applied.

Headers (`headers`)

set: A map of headers to set or overwrite.
add: A map of headers to append to existing values.
remove: A list of header keys to delete.

URL (`url`)

path: Set a new path for the request.
query: A map of query parameters to set, add, or remove.

Body (`body`)

Set this field to any object or value to replace the entire body.

🚀 Examples

1. Payload Mapping

Convert a legacy request body to the format expected by your new microservice.

config:
  expression: |
    {
      "body": {
        "new_id": body.oldId,
        "full_name": body.firstName & " " & body.lastName,
        "source": "crate-gateway"
      }
    }

2. Header Cleanup & Routing

Extract a tenant ID from a JWT (if using our auth plugin) and rewrite the path.

config:
  expression: |
    {
      "headers": {
        "remove": ["Authorization"]
      },
      "url": {
        "path": "/tenants/" & (body.tenant || "default") & "/api"
      }
    }