Our Hunters continue to bring us more technological news. This time, they talk about the Apicurio Registry, an artifact repository that allows you to store, query, modify, and verify schemas and specifications used in event-driven systems and API-based architectures.
Apicurio Registry allows developers to query a centralized catalog and applications to dynamically retrieve and update schemas, facilitating synchronization between versions of the schemas used in producer-consumer communication. It supports OpenAPI, AsyncAPI, GraphQL, Apache Avro, Google Protocol Buffers, JSON Schema, Kafka Connect schema, WSDL, and XML Schema (XSD).
Web interface
Apicurio Registry features a web interface for ease of use by developers, allowing them to do the following:
Consult the catalog of artifacts and search by group and name:
View and edit a specific artifact, allowing you to manage its associated validation rules:
View the contents of an artifact in a specific version:
View specification documentation, only available for OpenAPI and AsyncAPI specifications:
Dynamic artifact registration
Apicurio Registry allows client applications to dynamically manage artifacts stored in the repository, via a REST API or a Maven plugin.
REST API
The Apicurio Registry REST API offers the following functionalities for managing the repository and stored artifacts:
- Obtain and manage a specific artifact and its associated metadata, such as name, description, and tags.
- Search for artifacts by name, group, and identifier.
- Manage global validation rules for the repository and specific artifacts.
- Obtain and manage versions of a specific artifact.
- Manage repository properties.
Additionally, it provides APIs that support the Confluent Schema Registry and CNCF CloudEvents Schema Registry artifact repositories.
Maven Plugin
Apicurio Registry offers a Maven plugin that allows you to retrieve, update, and validate artifacts during the project build process.
An example of its use could be a producing application that updates its schemas in a repository and, in turn, another consuming application that downloads them during the compilation process, facilitating version synchronization between both applications.
To update and validate an artifact, you can configure a plugin with the " register " goal. When executed, the plugin updates the artifact in the repository. If the artifact doesn't meet any of the validation rules, an error will occur and it won't be updated.
In the following example, the plugin updates the artifact in the repository with the “Altia” group and id “ es.altia.demo.apicurio_registry_demo.schema.avro.Event,” using the contents of the “ event.avsc ” file. If the artifact doesn't exist in the repository, it will be created automatically. Additionally, setting the “ autoRefs ” option will update all references contained in the artifact.
To obtain an artifact, you can configure a plugin with the “download” goal that will download the artifact from the repository to the specified file.
In the following example, a plugin is configured to run in the Maven “ generate-sources ” phase. This plugin downloads the artifact with the group “ Altia ” and the ID “ es.altia.demo.apicurio_registry_demo.schema.avro.Event” into the file “ event.avsc”.
Schema validation
Apicurio Registry allows you to validate artifacts with a series of pre-established rules, which can be configured for a specific artifact or globally. The rules are checked upon modification of an artifact, canceling the update if any of them are not met.
The following types of rules are available:
- Validity, checks that the specification is valid, allowing checking only the syntax or the entire specification.
- Compatibility checks compatibility with previous versions, allowing you to set different options such as read or write compatibility.
- Integrity, checks that the references contained in the specification are valid.
Versioning
With each update to an artifact, Apicurio Registry creates a new version with the changes, always preserving the previous version. This allows you to query and retrieve each version an artifact has gone through.
Serialization and validation of Avro schemas at runtime
In Java projects, the Apicurio Registry allows you to dynamically retrieve Avro schemas, which are used in the serialization and deserialization of Kafka messages. This facilitates communication between producers and consumers.
Producers can use a serializer provided by Apicurio, which, before serializing a message, obtains the latest version of the schema hosted in the repository, thus ensuring that the issued messages comply with the latest version available in the repository.
In turn, consumers can use a deserializer provided by Apicurio, which obtains the latest version of the schema used and verifies the received message, ensuring that it complies with the latest version registered in the repository.
Deployment
The Apicurio Registry deployment is based on a web application running inside a Docker container , which hosts both the repository and the web interface. For data persistence, a connection to a Postgres database or a Kafka service is required.
Additionally, the Apicurio Registry Operator is available for OpenShift or Kubernetes clusters, allowing you to easily deploy and manage Apicurio Registry servers using manifests.
What can we conclude?
Apicurio Registry is a tool that allows you to manage communication schemes in a centralized repository, facilitating communication between systems and developers, as well as consultation and documentation.
It offers the following main advantages:
- Centralized repository, facilitating the consultation and distribution of message schemas and API specifications.
- Schema validation allows you to validate the content and compatibility of schemas.
- Versioning: Each change is applied as a new version, preserving previous versions and allowing for tracking of changes.
- Documentation, allows you to consult the documentation for OpenAPI and AsyncAPI type artifacts.
- Web interface, allowing developers to easily consult the catalog of artifacts.
On the other hand, it has the following disadvantages:
- Lack of custom validations, only allows enabling a series of preset validations.
- Limited artifact documentation, automatic documentation is only available for OpenAPI and AsyncAPI artifacts.
- Lack of test requests, which does not allow requests to be made to the service for testing, as other documentation tools allow.
- Tools oriented to Java projects, the tools provided for validating, obtaining and updating schemas are developed for Java projects, although using the provided REST API, they could be implemented for any type of project.
In conclusion, Apicurio Registry is a tool to consider, especially in projects based on distributed systems , which usually make use of a large number of communication schemes spread between different applications.
Below, we can see a video of its operation:
Want to know more about Hunters?
Being a Hunter means accepting the challenge of testing new solutions that deliver differentiated results. Join the Hunters program and become part of a cross-functional group capable of generating and transferring knowledge.
Get ahead of the digital solutions that will drive our growth. Find more information about Hunters on the website.
Joan Galiana
Software Engineer
Altia
