Logo Event-Driven Architecture Live

Schema Registry — Apicurio

¿Qué es Apicurio Registry?

Apicurio Registry es un schema registry open source que almacena y gestiona esquemas de datos y APIs. Es parte del ecosistema de Streams for Apache Kafka.

Formatos soportados:

  • Apache Avro

  • JSON Schema

  • Protobuf

  • OpenAPI

  • AsyncAPI

  • GraphQL

  • WSDL / XML Schema

¿Por qué un Schema Registry?

En un pipeline CDC, los eventos que Debezium produce tienen una estructura definida. Sin un schema registry:

  • Los consumidores no saben qué formato esperar

  • Cambios en la estructura de las tablas pueden romper consumidores

  • No hay validación de datos en tránsito

Con Apicurio Registry:

  • Los schemas se registran y versionan centralmente

  • Los productores validan contra el schema antes de enviar

  • Los consumidores obtienen el schema automáticamente

  • Evolución de schemas compatible (forward, backward, full)

Despliegue en OpenShift

apiVersion: registry.apicur.io/v1
kind: ApicurioRegistry
metadata:
  name: apicurio-registry
  namespace: kafka-cdc
spec:
  configuration:
    persistence: kafkasql
    kafkasql:
      bootstrapServers: cdc-cluster-kafka-bootstrap.kafka-cdc.svc:9092
  deployment:
    replicas: 1

El storage kafkasql usa Kafka como backend de persistencia — no requiere base de datos adicional.

Acceso a la UI

La interfaz web de Apicurio Registry está disponible en:

https://apicurio-registry-kafka-cdc.apps.cluster-l9nhj.dynamic.redhatworkshops.io

Desde ahí podes:

  • Explorar schemas registrados

  • Ver versiones y compatibilidad

  • Registrar nuevos schemas manualmente

  • Ver el contenido de cada schema

Integración con Debezium

Para usar Apicurio como serializer en Debezium, se configura el converter en KafkaConnect:

config:
  key.converter: io.apicurio.registry.utils.converter.AvroConverter
  key.converter.apicurio.registry.url: http://apicurio-registry-service.kafka-cdc.svc:8080/apis/registry/v2
  key.converter.apicurio.registry.auto-register: "true"
  value.converter: io.apicurio.registry.utils.converter.AvroConverter
  value.converter.apicurio.registry.url: http://apicurio-registry-service.kafka-cdc.svc:8080/apis/registry/v2
  value.converter.apicurio.registry.auto-register: "true"
En este demo usamos JSON converter por simplicidad, pero la integración con Avro via Apicurio está lista para habilitarse.

How it Works

Ciclo de validación de schemas

El Schema Registry actúa como un contrato vivo entre productores y consumidores:

  1. Un producer (Debezium, Camel) serializa un mensaje y envía el schema al registry (si auto-register=true).

  2. Apicurio valida el schema contra las reglas globales configuradas:

    • VALIDITY — el schema debe ser sintácticamente correcto (JSON Schema válido, Avro válido, etc.)

    • COMPATIBILITY — el schema debe ser compatible con la versión anterior según la política elegida

  3. Si la validación pasa, Apicurio asigna un globalId numérico al schema y lo almacena.

  4. El producer incluye el globalId en el header del mensaje Kafka (no el schema completo — esto ahorra bandwidth).

  5. Un consumer recibe el mensaje, extrae el globalId del header, y obtiene el schema completo desde Apicurio para deserializar.

  6. Si el producer intenta registrar un schema incompatible (ej: eliminar un campo requerido), Apicurio rechaza el registro con HTTP 409, previniendo el breaking change antes de que llegue a Kafka.

Modos de compatibilidad

Modo Garantía

BACKWARD

Consumidores con schema nuevo pueden leer datos escritos con schema viejo. Permite agregar campos opcionales.

FORWARD

Consumidores con schema viejo pueden leer datos escritos con schema nuevo. Permite eliminar campos opcionales.

FULL

Combinación de BACKWARD + FORWARD. Solo permite agregar o eliminar campos opcionales.

NONE

Sin validación de compatibilidad — útil en desarrollo, riesgoso en producción.

Persistencia KafkaSQL

En esta demo, Apicurio usa kafkasql como backend: los schemas se almacenan como mensajes en topics internos de Kafka. Esto elimina la necesidad de una base de datos adicional y hereda la replicación y durabilidad de Kafka (RF=3).

API REST del Registry

Apicurio Registry expone una API REST completa:

# Listar artifacts
curl -s https://apicurio-registry-kafka-cdc.apps.<domain>/apis/registry/v2/groups/default/artifacts

# Registrar un schema
curl -X POST https://apicurio-registry-kafka-cdc.apps.<domain>/apis/registry/v2/groups/default/artifacts \
  -H "Content-Type: application/json; artifactType=JSON" \
  -H "X-Registry-ArtifactId: customer-schema" \
  -d '{
    "type": "object",
    "properties": {
      "id": {"type": "integer"},
      "first_name": {"type": "string"},
      "last_name": {"type": "string"},
      "email": {"type": "string", "format": "email"}
    },
    "required": ["id", "first_name", "last_name", "email"]
  }'

Documentación Oficial