Comment mettre de l'ordre dans vos API et schémas avec Apicurio Registry

Imaginez que vous construisez une architecture microservices où les données circulent via Kafka ou des requêtes REST. Vous avez accumulé une douzaine de schémas Avro, plusieurs spécifications OpenAPI et quelques fichiers Protobuf. À un moment donné, une équipe met à jour un schéma de message et le système d'une autre équipe « tombe en panne » parce qu'elle n'a pas été informée des modifications à temps. Ça vous parle ? Vous pourriez bien sûr stocker les schémas dans Git et les copier entre les projets, mais cela tourne rapidement au chaos.

J'ai découvert Apicurio Registry en cherchant une alternative aux solutions standard de gestion de contrats d'API. C'est un projet CNCF sandbox qui résout un problème précis : il fournit un référentiel centralisé pour vos API et schémas.

Pourquoi se compliquer si on a Git

La fonctionnalité clé ne se limite pas à déposer un fichier « sur une étagère » — il s'agit de la façon dont le registre fonctionne avec ces données. Apicurio Registry peut valider la compatibilité des schémas à la volée. Lorsqu'un service producteur tente de publier une nouvelle version d'un schéma, le registre peut bloquer la mise à jour si elle rompt la compatibilité descendante. Vous détectez l'erreur avant que des données incorrectes n'atterrissent dans la file de messages.

De plus, le projet gère le versioning pour vous. Chaque schéma bénéficie d'un cycle de vie clair, et les consommateurs savent toujours quelle version utiliser.

Ce qu'il y a sous le capot et comment ça fonctionne

Les développeurs d'Apicurio ont choisi Quarkus comme base, ce qui rend l'outil rapide et léger. Mais la partie la plus intéressante est la flexibilité des options de stockage. Auparavant, il existait un binaire distinct pour chaque base de données, et dans la version 3.0, ils sont passés à un seul artefact. Il suffit maintenant de définir la variable d'environnement APICURIO_STORAGE_KIND et de choisir parmi les options suivantes :

• SQL — le choix classique. Par défaut H2 (pratique pour les tests), mais en production, mieux vaut utiliser PostgreSQL ou SQL Server.
• KafkaSQL — stocke les données directement dans les topics Kafka. C'est utile si vous ne souhaitez pas ajouter une base de données relationnelle distincte à votre infrastructure et que vous avez déjà un cluster Kafka.
• GitOps — une option pour ceux qui veulent une gestion déclarative.

Pour ceux qui utilisent Kubernetes, un operator prêt à l'emploi est disponible. Les mises à jour transitent par les canaux OLM, donc maintenir une version à jour dans votre cluster ne sera pas trop douloureux.

Comment l'essayer

Le moyen le plus rapide de découvrir le système est d'exécuter l'image Docker prête à l'emploi. Mais il est important de retenir : l'interface utilisateur a été déplacée vers un conteneur distinct.

Pour exécuter le serveur lui-même :

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

Et pour l'interface :

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

Après cela, le tableau de bord de gestion sera accessible à l'adresse localhost:8888, et la documentation de l'API propre au registre à l'adresse localhost:8080/apis.

Si vous souhaitez déployer une configuration complète avec PostgreSQL pour des tests appropriés, le moyen le plus simple est de créer un fichier 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

Niveaux de build pour les impatients

Si vous décidez d'explorer le code source et de compiler le projet vous-même, le projet propose trois « niveaux » de build. Cela fait gagner beaucoup de temps.

En utilisant le flag -Dlocal, vous compilez uniquement le cœur du serveur et le SDK Java sans vérifications de style supplémentaires ni génération de Javadoc. Le build prend environ 3 minutes. Si vous avez besoin du package complet avec le SDK Go et les operators, utilisez -Dfull. C'est un excellent exemple de l'attention que le projet porte au temps des contributeurs.

Considérations de sécurité

Par défaut, le registre ne nécessite pas d'autorisation, ce qui est acceptable pour le développement local mais dangereux sur un réseau d'entreprise. L'outil prend en charge l'intégration OpenID Connect (OIDC). Vous pouvez connecter Keycloak ou tout autre serveur compatible en passant quelques variables d'environnement : QUARKUS_OIDC_AUTH_SERVER_URL et QUARKUS_OIDC_CLIENT_ID. La configuration couvre à la fois l'API REST et l'interface utilisateur.

Résumé : à qui cela s'adresse

Apicurio Registry sera certainement utile pour les équipes qui :

1. Utilisent activement Kafka et ont du mal à maintenir les schémas Avro/Protobuf.
2. Souhaitent automatiser les vérifications de compatibilité des API (OpenAPI/AsyncAPI).
3. Cherchent une alternative légère à Confluent Schema Registry qui n'est pas fortement couplée à un écosystème unique.

Le projet semble vivant, la documentation (même la documentation de l'API intégrée) est détaillée, et le passage à Quarkus rend l'exploitation agréable. Si vos microservices sont en « libre-service » en matière de contrats — essayez de consacrer une heure à déployer ce registre. Il y a de fortes chances qu'il résolve la plupart de vos problèmes de versioning de schémas.