Nuestros Hunters siguen trayéndonos más novedades tecnológicas. En esta ocasión nos hablan de Apicurio Registry, un repositorio de artefactos que permite almacenar, consultar, modificar y verificar esquemas y especificaciones utilizados en sistemas orientados a eventos y arquitecturas basadas en APIs.

Apicurio Registry permite a los desarrolladores consultar un catálogo centralizado y a las aplicaciones obtener y actualizar esquemas de forma dinámica, facilitando la sincronización entre versiones de los esquemas utilizados en la comunicación entre productores y consumidores. Es capaz de trabajar con OpenAPI, AsyncAPI, GraphQL, Apache Avro, Google Protocol Buffers, JSON Schema, Kafka Connect schema, WSDL y XML Schema (XSD).

Interfaz Web

Apicurio Registry cuenta con una interfaz web para facilitar su uso por parte de los desarrolladores, que permite realizar lo siguiente:

• Consultar el catálogo de artefactos y realizar búsquedas por grupo y nombre.

 

Artefactos disponibles en el grupo Altia mostrados en la interfaz web.

• Visualizar y editar un artefacto concreto, permitiendo gestionar sus reglas de validación asociadas.

 

Detalles de artefacto en interfaz web.

• Visualizar contenido de un artefacto en una versión concreta.

 

Contenido de un artefacto en una versión concreta.

• Visualizar la documentación de especificaciones, únicamente disponible en especificaciones de tipo OpenAPI y AsyncAPI.

 

Ejemplo de documentación en un esquema OpenAPI.

Registro dinámico de artefactos

Apicurio Registry permite a las aplicaciones cliente gestionar los artefactos almacenados en el repositorio de forma dinámica, a través de una API REST o un plugin maven.

API REST

La API REST de Apicurio Registry ofrece las siguientes funcionalidades para gestionar el repositorio y los artefactos almacenados:

• Obtener y gestionar un artefacto específico y sus metadatos asociados, como nombre, descripción y etiquetas.
• Realizar búsquedas de artefactos según nombre, grupo e identificador.
• Gestionar las reglas de validación globales al repositorio y de artefactos específicos.
• Obtener y gestionar versiones de un artefacto en concreto.
• Administrar propiedades del repositorio.

Además, proporciona APIs compatibles con los repositorios de artefactos Confluent Schema Registry y CNCF CloudEvents Schema Registry.

Plugin Maven

Apicurio Registry ofrece un plugin maven que permite obtener, actualizar y validar artefactos durante el proceso de construcción del proyecto.

Un ejemplo de su uso podría ser una aplicación productora que actualice sus esquemas en un repositorio y, a su vez, otra aplicación consumidora que los descargue, durante el proceso de compilación, facilitando la sincronización de versiones entre ambas aplicaciones.

Para la actualización y validación de un artefacto se puede configurar un plugin con el goal “register”. Al ejecutarse, el plugin actualiza el artefacto en el repositorio y, si el artefacto no cumple con alguna de las reglas de validación, se producirá un error y no se actualizará.

En el siguiente ejemplo, el plugin actualiza en el repositorio el artefacto en el grupo “Altia” e id “es.altia.demo.apicurio_registry_demo.schema.avro.Event”, utilizando el contenido del fichero “event.avsc”. Si el artefacto no existe en el repositorio, se creará automáticamente. Además, al establecer la opción “autoRefs”, se actualizarán todas las referencias contenidas en el artefacto.

 

Ejemplo de configuración para actualización de artefactos en un repositorio con plugin maven.

Para la obtención de un artefacto, se puede configurar un plugin con el goal “download” que descargará el artefacto del repositorio en el fichero establecido.

En el siguiente ejemplo, se configura un plugin que se ejecuta en la fase maven “generate-sources”. Este plugin, descarga el artefacto con grupo “Altia” e id “es.altia.demo.apicurio_registry_demo.schema.avro.Event” en el fichero “event.avsc”.
 

 

Ejemplo de configuración para descarga de artefactos en un repositorio con plugin Maven.

Validación de esquemas

Apicurio Registry permite validar los artefactos con una serie de reglas preestablecidas, que pueden ser configuradas para un artefacto concreto o de forma global. Las reglas son comprobadas con la modificación de un artefacto, cancelando la actualización en el caso de que no se cumpla alguna de ellas.

Están disponibles los siguientes tipos de reglas:

• Validez, comprueba que la especificación es válida, permitiendo comprobar únicamente la sintaxis o la especificación completa.
• Compatibilidad, comprueba la compatibilidad con versiones anteriores, permitiendo establecer diferentes opciones como compatibilidad de lectura o escritura.
• Integridad, comprueba que las referencias contenidas en la especificación son válidas.

Versionado

Con cada actualización de un artefacto, Apicurio Registry crea una nueva versión con los cambios, conservando siempre la versión anterior. Esto permite consultar y obtener cada una de las versiones por la que ha pasado un artefacto.

Serialización y validación de esquemas Avro en tiempo de ejecución

En proyectos Java, Apicurio Registry permite obtener de forma dinámica esquemas Avro, que se utilizan en la serialización y deserialización de mensajes Kafka. Facilitando la comunicación entre productores y consumidores.

 

Ejemplo de versiones disponibles en un artefacto.

Los productores pueden utilizar un serializador provisto por Apicurio, que previamente a serializar un mensaje, obtiene la última versión del esquema alojada en repositorio, asegurando así que los mensajes emitidos cumplen con la última versión disponible en el repositorio.

 

Ejemplo configuración de serializador en productor.

A su vez, los consumidores pueden utilizar un deserializador provisto por Apicurio, que obtiene la última versión del esquema utilizado y verifica el mensaje recibido, asegurando que cumple con la última versión registrada en el repositorio.

 

Ejemplo configuración de deserializador en consumidor.

 

 

Despliegue

El despliegue de Apicurio Registry se basa en una aplicación web ejecutada dentro de un contenedor Docker, que aloja tanto el repositorio como la interfaz web. Para la persistencia de datos, se requiere una conexión a una base de datos Postgres o a un servicio Kafka.
Además, se encuentra disponible Apicurio Registry Operator para clústeres OpenShift o Kubernetes, que permite desplegar y gestionar servidores Apicurio Registry de manera sencilla mediante manifiestos.

¿Qué podemos concluir?

Apicurio Registry es una herramienta que permite gestionar esquemas de comunicación en un repositorio centralizado, facilitando la comunicación entre sistemas y a los desarrolladores, la consulta y documentación.
Ofrece las siguientes ventajas principales:

• Repositorio centralizado, facilita la consulta y distribución de esquemas de mensajes y especificaciones APIs.
• Validación de esquemas, permite validar el contenido y compatibilidad de los esquemas.
• Versionado, cada cambio se aplica como una nueva versión, conservando las versiones anteriores y permitiendo un seguimiento de las modificaciones.
• Documentación, permite consultar la documentación de los artefactos de tipo OpenAPI y AsyncAPI.
• Interfaz web, permite a desarrolladores consultar de forma sencilla el catálogo de artefactos.

Por otra parte, tiene las siguientes desventajas:

• Falta de validaciones personalizadas, solo permite habilitar una serie de validaciones preestablecidas.
• Documentación de artefactos limitada, la documentación automática únicamente está disponible para artefactos de tipo OpenAPI y AsyncAPI.
• Falta de peticiones de prueba, no permite realizar peticiones al servicio para realizar pruebas, como permiten otras herramientas de documentación.
• Herramientas orientadas a proyectos Java, las herramientas proporcionadas para la validación, obtención y actualización de esquemas están desarrolladas para proyectos Java, aunque utilizando la API REST provista, se podrían implementar para cualquier tipo de proyecto.

En conclusión, Apicurio Registry es una herramienta a tener en cuenta, especialmente en proyectos basados en sistemas distribuidos, que suelen hacer uso de un gran número de esquemas para la comunicación esparcidos entre diferentes aplicaciones.

A continuación, podemos ver un vídeo de su funcionamiento:

¿Quieres saber más sobre Hunters?

Ser un hunter es aceptar el reto de probar nuevas soluciones que aporten resultados diferenciales. Únete al programa Hunters y forma parte de un grupo transversal con capacidad de generar y transferir conocimiento.

Anticípate a las soluciones digitales que nos harán crecer. Consulta más información sobre Hunters en la web.

Joan Galiana

Ingeniero de Software en Altia