json-to-xml.md

description
This page provides the technical details of the JSON to XML policy

JSON to XML

Overview

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:

• Examples
• Configuration
• Compatibility Matrix
• Errors
• Changelogs

Examples

{% hint style="warning" %} This policy can be applied to all Gravitee APIs: v2 APIs, v4 proxy APIs, and v4 message APIs. {% endhint %}

{% tabs %} {% tab title="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 %}

Configuration

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 %}

Phases

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

Options

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

Compatibility matrix

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+

Errors

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

Nested objects

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.

Changelogs

{% @github-files/github-code-block url="https://github.com/gravitee-io/gravitee-policy-json-xml/blob/master/CHANGELOG.md" %}