> For the complete documentation index, see [llms.txt](https://docs.digitalapi.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalapi.ai/api-gateway/plugin-reference/plugins-transformation.md).
# Transformation plugins
Plugins in this category rewrite the request or response on the fly: add or remove headers, swap parameters, change the body, fold or split JSON. Attach them when the backend expects a slightly different shape than the consumer is sending or vice versa. The catalogue ships 9 Transformation plugins.
{% hint style="info" %}
**In this category:** [`attach-consumer-label`](#attach-consumer-label), [`body-transformer`](#body-transformer), [`degraphql`](#degraphql), [`fault-injection`](#fault-injection), [`grpc-transcode`](#grpc-transcode), [`grpc-web`](#grpc-web), [`mocking`](#mocking), [`proxy-rewrite`](#proxy-rewrite), [`response-rewrite`](#response-rewrite)
{% endhint %}
### `attach-consumer-label`
The `attach-consumer-label` plugin attaches custom consumer-related labels, in addition to `X-Consumer-Username` and `X-Credential-Indentifier`, to authenticated requests, for upstream services to differentiate between consumers and implement additional logics.
{% hint style="info" %}
**Priority** `2399` · **Category** Transformation · **Required** `headers`
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid values | Description |
| ------- | ------ | -------- | ------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| headers | object | True | | | Key-value pairs of consumer labels to be attached to request headers, where key is the request header name, such as `X-Consumer-Role`, and the value is a reference to the custom label key, such as `$role`. Note that the value should always start with a dollar sign (`$`). If a referenced consumer value is not configured on the consumer, the corresponding header will not be attached to the request. |
### `body-transformer`
The `body-transformer` Plugin performs template-based transformations to transform the request and/or response bodies from one format to another, for example, from JSON to JSON, JSON to HTML, or XML to YAML.
{% hint style="info" %}
**Priority** `1080` · **Category** Transformation
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid values | Description |
| ----------------------------- | ------- | -------- | ------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `request` | object | False | | | Request body transformation configuration. |
| `request.input_format` | string | False | | \[`xml`,`json`,`encoded`,`args`,`plain`,`multipart`] | Request body original media type. If unspecified, the value would be determined by the `Content-Type` header to apply the corresponding decoder. The `xml` option corresponds to `text/xml` media type. The `json` option corresponds to `application/json` media type. The `encoded` option corresponds to `application/x-www-form-urlencoded` media type. The `args` option corresponds to GET requests. The `plain` option corresponds to `text/plain` media type. The `multipart` option corresponds to `multipart/related` media type. If the media type is neither type, the value would be left unset and the transformation template will be directly applied. |
| `request.template` | string | True | | | Request body transformation template. The template uses [lua-resty-template](https://github.com/bungle/lua-resty-template) syntax. See the [template syntax](https://github.com/bungle/lua-resty-template#template-syntax) for more details. You can also use auxiliary functions `_escape_json()` and `_escape_xml()` to escape special characters such as double quotes, `_body` to access request body, and `_ctx` to access context variables. |
| `request.template_is_base64` | boolean | False | false | | Set to true if the template is base64 encoded. |
| `response` | object | False | | | Response body transformation configuration. |
| `response.input_format` | string | False | | \[`xml`,`json`] | Response body original media type. If unspecified, the value would be determined by the `Content-Type` header to apply the corresponding decoder. If the media type is neither `xml` nor `json`, the value would be left unset and the transformation template will be directly applied. |
| `response.template` | string | True | | | Response body transformation template. |
| `response.template_is_base64` | boolean | False | false | | Set to true if the template is base64 encoded. |
### `degraphql`
The `degraphql` Plugin is used to support decoding RESTful API to GraphQL.
{% hint style="info" %}
**Priority** `509` · **Category** Transformation · **Required** `query`
{% endhint %}
Configuration and details
| Name | Type | Required | Description |
| --------------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| query | string | True | The GraphQL query sent to the upstream |
| operation\_name | string | False | The name of the operation, is only required if multiple operations are present in the query. |
| variables | array | False | The variables used in the GraphQL query |
### `fault-injection`
The `fault-injection` Plugin can be used to test the resiliency of your application. This Plugin will be executed before the other configured Plugins.
{% hint style="info" %}
**Priority** `11000` · **Category** Transformation
{% endhint %}
Configuration and details
The `abort` attribute will directly return the specified HTTP code to the client and skips executing the subsequent Plugins.
The `delay` attribute delays a request and executes the subsequent Plugins.
| Name | Type | Requirement | Default | Valid | Description |
| ------------------ | -------- | ----------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| abort.http\_status | integer | required | | \[200, ...] | HTTP status code of the response to return to the client. |
| abort.body | string | optional | | | Body of the response returned to the client. Nginx variables like `client addr: $remote_addr\n` can be used in the body. |
| abort.headers | object | optional | | | Headers of the response returned to the client. The values in the header can contain Nginx variables like `$remote_addr`. |
| abort.percentage | integer | optional | | \[0, 100] | Percentage of requests to be aborted. |
| abort.vars | array\[] | optional | | | Rules which are matched before executing fault injection. See lua-resty-expr for a list of available expressions. |
| delay.duration | number | required | | | Duration of the delay. Can be decimal. |
| delay.percentage | integer | optional | | \[0, 100] | Percentage of requests to be delayed. |
| delay.vars | array\[] | optional | | | Rules which are matched before executing fault injection. See lua-resty-expr for a list of available expressions. |
### `grpc-transcode`
The `grpc-transcode` Plugin converts between HTTP and gRPC requests.
{% hint style="info" %}
**Priority** `506` · **Category** Transformation · **Required** `proto_id`, `service`, `method`
{% endhint %}
Configuration and details
AILIX takes in an HTTP request, transcodes it and forwards it to a gRPC service, gets the response and returns it back to the client in HTTP format.
| Name | Type | Required | Default | Description |
| ---------------------- | --------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| proto\_id | string/integer | True | | id of the the proto content. |
| service | string | True | | Name of the gRPC service. |
| method | string | True | | Method name of the gRPC service. |
| deadline | number | False | 0 | Deadline for the gRPC service in ms. |
| pb\_option | array\[string([pb\_option\_def](#options-for-pb_option))] | False | | protobuf options. |
| show\_status\_in\_body | boolean | False | false | Whether to display the parsed `grpc-status-details-bin` in the response body |
| status\_detail\_type | string | False | | The message type corresponding to the [details](https://github.com/googleapis/googleapis/blob/b7cb84f5d42e6dba0fdcc2d8689313f6a8c9d7b9/google/rpc/status.proto#L46) part of `grpc-status-details-bin`, if not specified, this part will not be decoded |
| Type | Valid values |
| --------------- | ----------------------------------------------------------------------------------------- |
| enum as result | `enum_as_name`, `enum_as_value` |
| int64 as result | `int64_as_number`, `int64_as_string`, `int64_as_hexstring` |
| default values | `auto_default_values`, `no_default_values`, `use_default_values`, `use_default_metatable` |
| hooks | `enable_hooks`, `disable_hooks` |
### `grpc-web`
The `grpc-web` Plugin is a proxy Plugin that can process [gRPC Web](https://github.com/grpc/grpc-web) requests from JavaScript clients to a gRPC service.
{% hint style="info" %}
**Priority** `505` · **Category** Transformation
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Description |
| -------------------- | ------ | -------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| cors\_allow\_headers | string | False | "content-type,x-grpc-web,x-user-agent" | Headers in the request allowed when accessing a cross-origin resource. Use `,` to add multiple headers. |
### `mocking`
The `mocking` Plugin is used for mocking an API. When executed, it returns random mock data in the format specified and the request is not forwarded to the Upstream.
{% hint style="info" %}
**Priority** `10900` · **Category** Transformation
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Description |
| ------------------ | ------- | -------- | ---------------- | --------------------------------------------------------------------------------------- |
| delay | integer | False | | Response delay in seconds. |
| response\_status | integer | False | 200 | HTTP status code of the response. |
| content\_type | string | False | application/json | Header `Content-Type` of the response. |
| response\_example | string | False | | Body of the response, support use variables, like `$remote_addr $consumer_name`. |
| response\_schema | object | False | | The JSON schema object for the response. Works when `response_example` is unspecified. |
| with\_mock\_header | boolean | False | true | When set to `true`, adds a response header `x-mock-by: AILIX/{version}`. |
| response\_headers | object | false | | Headers to be added in the mocked response. Example: `{"X-Foo": "bar", "X-Few": "baz"}` |
### `proxy-rewrite`
The `proxy-rewrite` Plugin offers options to rewrite requests that AILIX forwards to Upstream services. With this plugin, you can modify the HTTP methods, request destination Upstream addresses, request headers, and more.
{% hint style="info" %}
**Priority** `1008` · **Category** Transformation
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid values | Description |
| ------------------------------- | -------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| uri | string | False | | | New Upstream URI path. Value supports [NGINX variables](https://nginx.org/en/docs/http/ngx_http_core_module.html). For example, `$arg_name`. |
| method | string | False | | \["GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS","MKCOL", "COPY", "MOVE", "PROPFIND", "PROPFIND","LOCK", "UNLOCK", "PATCH", "TRACE"] | HTTP method to rewrite requests to use. |
| regex\_uri | array\[string] | False | | | Regular expressions used to match the URI path from client requests and compose a new Upstream URI path. When both `uri` and `regex_uri` are configured, `uri` has a higher priority. The array should contain one or more **key-value pairs**, with the key being the regular expression to match URI against and value being the new Upstream URI path. For example, with `["^/iresty/(. *)/(. *)", "/$1-$2", ^/theothers/*", "/theothers"]`, if a request is originally sent to `/iresty/hello/world`, the Plugin will rewrite the Upstream URI path to `/iresty/hello-world`; if a request is originally sent to `/theothers/hello/world`, the Plugin will rewrite the Upstream URI path to `/theothers`. |
| host | string | False | | | Set [`Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host) request header. |
| headers | object | False | | | Header actions to be executed. Can be set to objects of action verbs `add`, `remove`, and/or `set`; or an object consisting of headers to be `set`. When multiple action verbs are configured, actions are executed in the order of `add`, `remove`, and `set`. |
| headers.add | object | False | | | Headers to append to requests. If a header already present in the request, the header value will be appended. Header value could be set to a constant, one or more [NGINX variables](https://nginx.org/en/docs/http/ngx_http_core_module.html), or the matched result of `regex_uri` using variables such as `$1-$2-$3`. |
| headers.set | object | False | | | Headers to set to requests. If a header already present in the request, the header value will be overwritten. Header value could be set to a constant, one or more [NGINX variables](https://nginx.org/en/docs/http/ngx_http_core_module.html), or the matched result of `regex_uri` using variables such as `$1-$2-$3`. Should not be used to set `Host`. |
| headers.remove | array\[string] | False | | | Headers to remove from requests. |
| use\_real\_request\_uri\_unsafe | boolean | False | false | | If true, bypass URI normalization and allow for the full original request URI. Enabling this option is considered unsafe. |
### `response-rewrite`
The `response-rewrite` Plugin offers options to rewrite responses that AILIX and its Upstream services return to clients. With the Plugin, you can modify HTTP status codes, request headers, response body, and more.
{% hint style="info" %}
**Priority** `899` · **Category** Transformation
{% endhint %}
Configuration and details
For instance, you can use this Plugin to:
* Support [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) by setting `Access-Control-Allow-*` headers.
* Indicate redirection by setting HTTP status codes and `Location` header.
:::tip
You can also use the redirect Plugin to set up redirects.
:::
| Name | Type | Required | Default | Valid values | Description |
| --------------- | -------------- | -------- | ------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status\_code | integer | False | | \[200, 598] | New HTTP status code in the response. If unset, falls back to the original status code. |
| body | string | False | | | New response body. The `Content-Length` header would also be reset. Should not be configured with `filters`. |
| body\_base64 | boolean | False | false | | If true, decode the response body configured in `body` before sending to client, which is useful for image and protobuf decoding. Note that this configuration cannot be used to decode Upstream response. |
| headers | object | False | | | Actions to be executed in the order of `add`, `remove`, and `set`. |
| headers.add | array\[string] | False | | | Headers to append to requests. If a header already present in the request, the header value will be appended. Header value could be set to a constant, or one or more [Nginx variables](https://nginx.org/en/docs/http/ngx_http_core_module.html). |
| headers.set | object | False | | | Headers to set to requests. If a header already present in the request, the header value will be overwritten. Header value could be set to a constant, or one or more[Nginx variables](https://nginx.org/en/docs/http/ngx_http_core_module.html). |
| headers.remove | array\[string] | False | | | Headers to remove from requests. |
| vars | array\[array] | False | | | An array of one or more matching conditions in the form of lua-resty-expr. |
| filters | array\[object] | False | | | List of filters that modify the response body by replacing one specified string with another. Should not be configured with `body`. |
| filters.regex | string | True | | | RegEx pattern to match on the response body. |
| filters.scope | string | False | "once" | \["once","global"] | Scope of substitution. `once` substitutes the first matched instance and `global` substitutes globally. |
| filters.replace | string | True | | | Content to substitute with. |
| filters.options | string | False | "jo" | | RegEx options to control how the match operation should be performed. See [Lua NGINX module](https://github.com/openresty/lua-nginx-module#ngxrematch) for the available options. |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.digitalapi.ai/api-gateway/plugin-reference/plugins-transformation.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.