Transform RESTful requests

Overview

Relixy can rewrite the URL, body and headers from RESTful requests before forwarding them to the upstream and rewrite responses before returning them to the client. Transformations are configured per-operation using the x-rely-proxy-action vendor extension on an OpenAPI operation object.

The extension accepts one object with a type field plus optional request and response sections.

Field	Required	Description
type	Yes	Always rest for REST operations.
request	No	Transformation applied to the outgoing request.
response	No	Transformation applied to the incoming response.

Transformation

Example

The following example shows an operation that:

1. Rewrites the upstream path and transforms variables in the path template.
2. Adds custom header derived from a path parameter.
3. Transforms the request body to a different shape.
4. Transforms the response to a different shape.

paths:
  /users/{id}:
    get:
      x-rely-proxy-action:
        type: rest
        request:
          url: "/accounts/{id}"
          method: POST
          parameters:
            - in: path
              name: id
              path: param.id
            - in: header
              name: X-User-Id
              path: param.id
          body:
            type: jmespath
            template:
              type: object
              properties:
                account_id:
                  type: field
                  path: param.id
        response:
          contentType: application/json
          body:
            type: gotmpl
            template: |
              {
                "id": "{{.body.account_id}}",
                "displayName": "{{.body.display_name}}",
                "email": "{{.body.contact.email}}"
              }

Override the request path

Use request.url to replace the upstream path entirely. Path parameters from the original request are still available via templates.

x-rely-proxy-action:
  type: rest
  request:
    url: "/accounts/{id}"

You can define template variables in the path. The engine infers the equivalent parameter in the request path and replace them. Otherwise, you can defines custom parameters.

Transform request parameters

Use request.parameters to add or override parameters to the upstream request. Values are JMESPath expressions evaluated against the request data.

x-rely-proxy-action:
  type: rest
  request:
    url: "/accounts/{id}"
    parameters:
      - in: path
        name: id
        path: param.id
      - in: header
        name: X-User-Id
        path: param.id

The available input object for JMESPath expressions:

Key	Type	Description
param	object	Path parameters (e.g., param.id for {id})
query	object	Query string parameters
headers	object	Request headers (keys are lowercased)
body	any	Parsed request body.

Transform the request body

Use request.body with a Go template to rewrite the request body sent to the upstream.

x-rely-proxy-action:
  type: rest
  request:
    body:
      type: jmespath
      template:
        type: object
        properties:
          account_id:
            type: field
            path: param.id

The same data object (param, query, headers, body) is available in templates as the root context (.).

Transform the response body

Use response.body with a Go template to rewrite the response body returned to the client.

x-rely-proxy-action:
  type: rest
  response:
    contentType: application/json
    body:
      type: gotmpl
      template: |
        {
          "id": "{{.body.account_id}}",
          "displayName": "{{.body.display_name}}",
          "email": "{{.body.contact.email}}"
        }

The template context for response transformations is the parsed JSON response body from the upstream, accessible as .body.