protobuf-to-json.md

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

Protobuf to JSON

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

Overview

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

{% hint style="warning" %} A JSON to Protobuf transformation policy is not yet available. {% endhint %}

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 protobuf-json 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 protobuf-json 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 protobuf-json policy:

{
    "name": "protobuf-2-json",
    "policy": "protobuf-json",
    "configuration": {
        "conversion": "protobuf-to-json",
        "json": {
            "includingDefaultValueFields": false,
            "preservingProtoFieldNames": false,
            "sortingMapKeys": false,
            "omittingInsignificantWhitespace": false
    },
    "protobufIn": {
        "schemaLocation": "inline",
        "inlineIn": {
            "normalizeSchema": false,
            "serializationFormat": "confluent",
            "schemaDefinition": "syntax = \"proto2\";\npackage test;\n\nmessage Payment {\n  required string id = 1;\n  required double amount = 2;\n}"
        }
    }
  }
}

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 protobuf-json policy.

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

{
    "name": "protobuf-2-json",
    "policy": "protobuf-json",
    "configuration": {
        "conversion": "json-to-protobuf",
        "protobufOut": {
            "schemaLocation": "schema-registry",
            "schemaRegistryOut": {
                "id": {
                    "origin": "inline",
                    "value": 2
                },
                "resourceName": "resource-name",
                "serializationFormat": "confluent"
            }
        }
    }
}

Currently, we only support Confluent serialization format. The protobuf-json 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 protobuf-json policy supports the following serialization formats:

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

Errors

Phase	Code	Error template key	Description
*	500	INVALID_PROTOBUF_TRANSFORMATION	When the transformation 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.