description |
---|
This page provides the technical details of the JSON to XML policy |
The json-xml
policy transforms JSON payloads to XML before either sending the payload to the backend system or returning it to the client.
Functional and implementation information for the json-xml
policy is organized into the following sections:
{% hint style="warning" %} This policy can be applied to v2 APIs, v4 HTTP proxy APIs, and v4 message APIs. It cannot be applied to v4 TCP proxy APIs. {% endhint %}
{% tabs %}
{% tab title="HTTP proxy API example" %}
For proxy APIs, the json-xml
policy is most commonly used for transforming JSON data before returning it to the client in the response
phase.
For example, the Gravitee echo API returns a JSON response when a GET
request is sent to https://api.gravitee.io/echo. The response is formatted as below:
{% code title="Default response" %}
{
"bodySize": 0,
"headers": {
"Accept": "*/*",
"Host": "api.gravitee.io",
"User-Agent": "{{user-agent-info}}",
"X-Gravitee-Request-Id": "{{generated-request-id}}",
"X-Gravitee-Transaction-Id": "{{generated-trx-id}}",
"accept-encoding": "deflate, gzip"
},
"query_params": {}
}
{% endcode %}
Adding a json-xml
policy on the response phase for a proxy API will transform the response output to:
{% code title="Transformed response" %}
<root>
<headers>
<Accept>*/*</Accept>
<Host>api.gravitee.io</Host>
<User-Agent>{{user-agent-info}}</User-Agent>
<X-Gravitee-Request-Id>{{generated-request-id}}</X-Gravitee-Request-Id>
<X-Gravitee-Transaction-Id>{{generated-trx-id}}</X-Gravitee-Transaction-Id>
<accept-encoding>deflate, gzip</accept-encoding>
</headers>
<query_params/>
<bodySize>0</bodySize>
</root>
{% endcode %} {% endtab %}
{% tab title="Message API example" %}
For message APIs, the json-xml
policy is used to transform the message content in either the publish or subscribe phase.
For example, you can create a message API with an HTTP GET entrypoint and a Mock endpoint. Suppose the endpoint is configured to return the message content as follows:
{% code title="Default message" %}
{ \"id\": \"1\", \"name\": \"bob\", \"v\": 2 }
{% endcode %}
Adding a json-xml
policy on the subscribe phase will return the payload to the client via the HTTP GET entrypoint as follows (the number of messages returned will vary by the number of messages specified in the Mock endpoint):
{% code title="Transformed messages" %}
{
"items": [
{
"content": "<root><id>1</id><name>bob</name><v>2</v></root>",
"id": "0"
},
{
"content": "<root><id>1</id><name>bob</name><v>2</v></root>",
"id": "1"
},
{
"content": "<root><id>1</id><name>bob</name><v>2</v></root>",
"id": "2"
},
{
"content": "<root><id>1</id><name>bob</name><v>2</v></root>",
"id": "3"
}
],
"pagination": {
"nextCursor": "3"
}
}
{% endcode %}
The output is the typical return structure for the HTTP GET entrypoint with each message content field transformed from JSON to XML.
{% hint style="info" %}
For the HTTP GET entrypoint specifically, the entire payload can be returned as XML by adding the "Accept": "application/json"
header to the GET request. In this case, the message content is transformed into CDATA and is therefore not treated as marked-up content for the purpose of the entrypoint using the Accept
header.
{% endhint %}
{% endtab %}
{% endtabs %}
Sample policy configuration is shown below:
{% code title="Sample Configuration" %}
{
"name": "Custom name",
"description": "Converts data from JSON to XML",
"policy": "json-xml",
"configuration": {
"scope": "RESPONSE",
"rootElement": "root"
}
}
{% endcode %}
The phases checked below are supported by the json-xml
policy:
v2 Phases | Compatible? | v4 Phases | Compatible? |
---|---|---|---|
onRequest | true | onRequest | true |
onResponse | true | onResponse | true |
onRequestContent | true | onMessageRequest | true |
onResponseContent | true | onMessageResponse | true |
The json-xml
policy can be configured with the following options:
Property | Required | Description | Type | Default |
---|---|---|---|---|
scope | legacy engine only | The execution scope (request or response ) | string | REQUEST |
rootElement | X | Root element name that’s enclose content | string | root |
The following is the compatibility matrix for APIM and the json-xml
policy:
Plugin Version | Supported APIM versions |
---|---|
1.x | 3.x |
3.x | 4.0+ |
Phase | HTTP status code | Error template key |
---|---|---|
onRequest | 400 | JSON_INVALID_PAYLOAD: Request payload cannot be transformed properly to XML |
onResponse | 500 | JSON_INVALID_PAYLOAD: Response payload cannot be transformed properly to XML |
onMessageRequest | 400 | JSON_INVALID_MESSAGE_PAYLOAD: Incoming message cannot be transformed properly to XML |
onMessageResponse | 500 | JSON_INVALID_MESSAGE_PAYLOAD: Outgoing message cannot be transformed properly to XML |
To limit the processing time in case of nested object, a default max depth of nested object has been defined to 100. This default value can be overriden using the environment variable gravitee_policy_jsonxml_maxdepth
.
{% @github-files/github-code-block url="https://github.com/gravitee-io/gravitee-policy-json-xml/blob/master/CHANGELOG.md" %}