avro-to-json.md

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

AVRO to JSON

{% hint style="warning" %} This feature requires Gravitee's Enterprise Edition. {% endhint %}

Overview

You can use the avro-json policy to apply a transformation (or mapping) on the request and/or response and/or message content.

This policy uses the Avro library. To serialize data in Avro, you need a schema. A schema can be provided inline in the policy configuration or with a schema registry.

Functional and implementation information for the avro-json policy is organized into the following sections:

• Examples
• Configuration
• Errors

Examples

{% 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" %} Example of inline request:

{
    "name": "avro-2-json",
    "description": "avro-2-json",
    "enabled": true,
    "policy": "avro-json",
    "configuration": {
        "conversion": "avro-to-json",
        "schemaLocation": "inline",
        "schemaDefinition": "{\"namespace\": \"io.confluent.examples.clients.basicavro\", \"type\": \"record\", \"name\": \"Payment\", \"fields\": [{\"name\": \"id\", \"type\": \"string\"}, {\"name\": \"amount\", \"type\": \"double\"}]}\n"
    }
}

{% endtab %}

{% tab title="Message API example" %} Example of inline publishing:

{
    "name": "avro-2-json",
    "description": "avro-2-json",
    "enabled": true,
    "policy": "avro-json",
    "configuration": {
        "conversion": "avro-to-json",
        "schemaLocation": "inline",
        "schemaDefinition": "{\"namespace\": \"io.confluent.examples.clients.basicavro\", \"type\": \"record\", \"name\": \"Payment\", \"fields\": [{\"name\": \"id\", \"type\": \"string\"}, {\"name\": \"amount\", \"type\": \"double\"}]}\n"
    }
}

{% endtab %} {% endtabs %}

Configuration

Inline schema

You can directly provide the schema to use in the policy configuration:

{
    "name": "avro-2-json",
    "policy": "avro-json",
    "configuration": {
        "conversion": "avro-to-json",
        "schemaLocation": "inline",
        "schemaDefinition": "{\"namespace\": \"io.confluent.examples.clients.basicavro\", \"type\": \"record\", \"name\": \"Payment\", \"fields\": [{\"name\": \"id\", \"type\": \"string\"}, {\"name\": \"amount\", \"type\": \"double\"}]}"
    }
}

Schema registry

To use a schema registry to fetch a schema, you will need to declare a Gravitee resource in your API in addition to this policy.

Currently, we only provide a resource to interact with Confluent Schema Registry. You can find the plugin here.

{
    "name": "avro-2-json",
    "policy": "avro-json",
    "configuration": {
        "conversion": "avro-to-json",
        "schemaLocation": "schema-registry",
        "serializationFormat": "confluent",
        "resourceName": "confluent-schema-registry"
    }
}

The policy will extract the schema ID from the binary and will use it to fetch the schema in the registry.

Serialization format

The avro-json policy supports the following serialization formats:

• confluent: The binary is generated using Confluent serialization format. This is the serialization format used by Gravitee by default and by the kafka-avro-serializer library.
• simple: The binary contains only the serialized Avro. The simple format can only be used for inline schema. If you serialize data "manually" (without kafka-serializer), the policy may not able to deserialize the binary.

Phases

Phases supported by the avro-json policy differ based on schema type.

Inline schema phases

Inline schema is not compatible with onRequestContent or onResponseContent (the body of v4 proxy APIs).

v2 Phases	Compatible?	v4 Phases	Compatible?
onRequest	true	onRequest	true
onResponse	true	onResponse	true
onRequestContent	false	onMessageRequest	true
onResponseContent	false	onMessageResponse	true

Schema registry phases

The use of Confluent Schema Registry is only available to transform messages on the onMessageResponse phase.

v2 Phases	Compatible?	v4 Phases	Compatible?
onRequest	false	onRequest	false
onResponse	false	onResponse	false
onRequestContent	false	onMessageRequest	false
onResponseContent	false	onMessageResponse	true

Errors

Code	Error template key	Description
500	INVALID_AVRO_TRANSFORMATION	The transform fails to be applied to the payload
500	UNSUPPORTED_CONFIGURATION_KEY	The policy configuration is not supported. For example, the policy needs a schema registry but also uses the simple serialization format.