Cómo imponer orden en APIs y esquemas con Apicurio Registry

Imagina que estás construyendo una arquitectura de microservicios donde los datos fluyen a través de Kafka o solicitudes REST. Has acumulado una docena de esquemas Avro, varias especificaciones OpenAPI y un puñado de archivos Protobuf. En algún momento, un equipo actualiza un esquema de mensaje y el sistema de otro equipo "se rompe" porque no se enteró de los cambios a tiempo. ¿Te suena familiar? Por supuesto, podrías almacenar los esquemas en Git y copiarlos entre proyectos, pero eso rápidamente se convierte en caos.

Descubrí Apicurio Registry mientras buscaba una alternativa a las soluciones estándar de gestión de contratos de API. Es un proyecto sandbox de CNCF que resuelve un punto de dolor específico: proporciona un repositorio centralizado para tus APIs y esquemas.

¿Por qué molestarse si tienes Git

La característica clave no es solo poner un archivo "en un estante" — se trata de cómo el registro trabaja con esos datos. Apicurio Registry puede validar la compatibilidad de esquemas sobre la marcha. Cuando un servicio productor intenta publicar una nueva versión de esquema, el registro puede bloquear la actualización si rompe la compatibilidad hacia atrás. Atrapas el error antes de que datos incorrectos lleguen a la cola de mensajes.

Además, el proyecto maneja el versionado por ti. Cada esquema obtiene un ciclo de vida claro, y los consumidores siempre saben qué versión usar.

Qué hay debajo del capó y cómo funciona

Los desarrolladores de Apicurio eligieron Quarkus como base, lo que hace que la herramienta sea rápida y ligera. Pero la parte más interesante es la flexibilidad en las opciones de almacenamiento. Anteriormente, había un binario separado para cada base de datos, y en la versión 3.0 cambiaron a un único artefacto. Ahora solo necesitas establecer la variable de entorno APICURIO_STORAGE_KIND y elegir entre las siguientes opciones:

• SQL — la opción clásica. Por defecto usa H2 (conveniente para pruebas), pero en producción es mejor usar PostgreSQL o SQL Server.
• KafkaSQL — almacena datos directamente en topics de Kafka. Esto es útil si no quieres agregar una base de datos relacional separada a tu infraestructura y ya tienes un cluster de Kafka.
• GitOps — una opción para quienes buscan gestión declarativa.

Para quienes usan Kubernetes, hay un operador listo para usar. Las actualizaciones llegan a través de canales OLM, así que mantener una versión actualizada en tu cluster no será demasiado doloroso.

Cómo probarlo

La forma más rápida de echar un vistazo al sistema es ejecutar la imagen Docker lista para usar. Pero es importante recordar: la interfaz de usuario se movió a un contenedor separado.

Para ejecutar el servidor en sí:

docker run -it -p 8080:8080 apicurio/apicurio-registry:latest-snapshot

Y para la interfaz:

docker run -it -p 8888:8080 apicurio/apicurio-registry-ui:latest-snapshot

Después de eso, el panel de gestión estará disponible en localhost:8888, y la documentación de la API del registro estará en localhost:8080/apis.

Si quieres desplegar una configuración completa con PostgreSQL para pruebas adecuadas, la forma más fácil es crear un archivo Docker Compose:

services:
  postgres:
    image: postgres
    environment:
      POSTGRES_USER: apicurio-registry
      POSTGRES_PASSWORD: password
  app:
    image: apicurio/apicurio-registry:3.0.0
    ports:
      - 8080:8080
    environment:
      APICURIO_STORAGE_KIND: 'sql'
      APICURIO_STORAGE_SQL_KIND: 'postgresql'
      APICURIO_DATASOURCE_URL: 'jdbc:postgresql://postgres/apicurio-registry'
      APICURIO_DATASOURCE_USERNAME: apicurio-registry
      APICURIO_DATASOURCE_PASSWORD: password

Niveles de compilación para los impacientes

Si decides profundizar en el código fuente y compilar el proyecto tú mismo, el proyecto ofrece tres "niveles" de compilación. Esto ahorra mucho tiempo.

Usando el flag -Dlocal, compilas solo el núcleo del servidor y el SDK de Java sin verificaciones de estilo adicionales ni generación de Javadoc. La compilación toma aproximadamente 3 minutos. Si necesitas el paquete completo con Go SDK y operadores, usa -Dfull. Este es un gran ejemplo de cómo el proyecto cuida el tiempo de los contribuidores.

Consideraciones de seguridad

De fábrica, el registro no requiere autorización, lo cual está bien para desarrollo local pero es peligroso en una red corporativa. La herramienta soporta integración con OpenID Connect (OIDC). Puedes conectar Keycloak o cualquier otro servidor compatible pasando un par de variables de entorno: QUARKUS_OIDC_AUTH_SERVER_URL y QUARKUS_OIDC_CLIENT_ID. La configuración cubre tanto la API REST como la interfaz de usuario.

Resumen: a quién debería interesarle

Apicurio Registry definitivamente será útil para equipos que:

1. Usan activamente Kafka y tienen dificultades para mantener esquemas Avro/Protobuf.
2. Quieren automatizar las verificaciones de compatibilidad de API (OpenAPI/AsyncAPI).
3. Buscan una alternativa ligera a Confluent Schema Registry que no esté acoplada a un solo ecosistema.

El proyecto parece vivo, la documentación (incluso la documentación de API integrada) es detallada, y el cambio a Quarkus hace que sea agradable de operar. Si tus microservicios tienen una situación de "libre para todos" en cuanto a contratos — intenta pasar una hora levantando este registro. Lo más probable es que resuelva la mayoría de tus problemas de versionado de esquemas.