avro-to-protobuf.md

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

AVRO to Protobuf

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

Overview

You can use the avro-protobuf 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. There are two ways to provide a schema:

• Inline in the policy configuration
• With a schema registry

To serialize data in Protobuf, you need a schema. There are two ways to provide a schema:

• Inline in the policy configuration
• With a schema registry

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

• Configuration
• Errors

Configuration

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

Phases

The phases checked below are supported by the avro-protobuf policy:

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

Inline Schema

You can provide the schema to use directly in the configuration of the avro-protobuf policy:

{
    "name": "avro-2-protobuf",
    "policy": "avro-protobuf",
    "configuration": {
        "conversion": "avro-to-protobuf",
        "avro": {
            "inlineConfig": {
                "schemaDefinition": "{\"namespace\": \"io.confluent.examples.clients.basicavro\", \"type\": \"record\", \"name\": \"Payment\", \"fields\": [{\"name\": \"id\", \"type\": \"string\"}, {\"name\": \"amount\", \"type\": \"double\"}]}\n",
                "serializationFormat": "confluent"
            }
        },
        "protobuf": {
            "inlineConfig": {
                "schemaDefinition": "syntax = \"proto2\"; package test; message Payment {required string id = 1; required double amount = 2; }",
                "serializationFormat": "confluent"
            }
        }
    }
}

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 the avro-protobuf policy.

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

{
    "name": "avro-2-protobuf",
    "policy": "avro-protobuf",
    "configuration": {
        "conversion": "avro-to-protobuf",
        "avro": {
            "schemaRegistryConfig": {
                "resourceName": "confluent-schema-registry"
            }
        },
        "protobuf": {
            "schemaRegistryConfig": {
                "resourceName": "confluent-schema-registry",
                "schemaIdConfig": {
                    "schemaIdLocation": "inline",
                    "schemaId": 1
                }
            }
        }
    }
}

Currently, we only support Confluent serialization format. The avro-protobuf policy will extract the schema ID from the binary and use it to fetch the schema in the registry.

{% hint style="warning" %} The use of a schema registry is only available to transform messages on the onMessageResponse phase. {% endhint %}

Serialization format

The avro-protobuf policy supports the following serialization formats:

• simple: The binary contains only the serialized Protobuf/AVRO
• confluent: The binary has been generated using Confluent serialization format

Errors

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