Come portare ordine in API e schemi con Apicurio Registry

Immagina di costruire un'architettura a microservizi in cui i dati scorrono attraverso Kafka o richieste REST. Hai accumulato una dozzina di schemi Avro, diverse specifiche OpenAPI e una manciata di file Protobuf. A un certo punto, un team aggiorna uno schema di messaggio e il sistema di un altro team "si rompe" perché non ha appreso le modifiche in tempo. Ti suona familiare? Potresti ovviamente memorizzare gli schemi in Git e copiarli tra i progetti, ma questo rapidamente si trasforma in caos.

Ho scoperto Apicurio Registry mentre cercavo un'alternativa alle soluzioni standard di gestione dei contratti API. È un progetto CNCF sandbox che risolve un punto critico specifico: fornisce un repository centralizzato per le tue API e i tuoi schemi.

Perché preoccuparsi se hai Git

La funzionalità chiave non riguarda solo il mettere un file "sullo scaffale" — si tratta di come il registry lavora con quei dati. Apicurio Registry può validare la compatibilità degli schemi al volo. Quando un servizio producer tenta di pubblicare una nuova versione dello schema, il registry può bloccare l'aggiornamento se rompe la compatibilità all'indietro. Catturi l'errore prima che dati errati finiscano nella coda di messaggi.

Inoltre, il progetto gestisce il versioning per te. Ogni schema ottiene un ciclo di vita chiaro, e i consumer sanno sempre quale versione usare.

Cosa c'è sotto il cofano e come funziona

Gli sviluppatori di Apicurio hanno scelto Quarkus come fondamento, rendendo lo strumento veloce e leggero. Ma la parte più interessante è la flessibilità nelle opzioni di storage. In precedenza, c'era un binario separato per ogni database, e nella versione 3.0 sono passati a un singolo artefatto. Ora basta impostare la variabile di ambiente APICURIO_STORAGE_KIND e scegliere tra le seguenti opzioni:

• SQL — la scelta classica. Di default usa H2 (conveniente per i test), ma in produzione è meglio usare PostgreSQL o SQL Server.
• KafkaSQL — memorizza i dati direttamente negli argomenti Kafka. È utile se non vuoi aggiungere un database relazionale separato alla tua infrastruttura e hai già un cluster Kafka.
• GitOps — un'opzione per chi vuole una gestione dichiarativa.

Per chi usa Kubernetes, c'è un operator già pronto. Gli aggiornamenti arrivano attraverso i canali OLM, quindi mantenere una versione aggiornata nel tuo cluster non sarà troppo doloroso.

Come provarlo

Il modo più veloce per dare un'occhiata al sistema è eseguire l'immagine Docker già pronta. Ma è importante ricordare: l'interfaccia UI è stata spostata in un container separato.

Per eseguire il server stesso:

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

E per l'interfaccia:

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

Dopo di ciò, la dashboard di gestione sarà disponibile su localhost:8888, e la documentazione per l'API nativa del registry sarà su localhost:8080/apis.

Se vuoi distribuire una configurazione completa con PostgreSQL per test appropriati, il modo più semplice è creare un file 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

Livelli di build per gli impazienti

Se decidi di approfondire il codice sorgente e buildare il progetto da solo, il progetto offre tre "livelli" di build. Questo fa risparmiare molto tempo.

Usando il flag -Dlocal, buildi solo il core del server e il Java SDK senza controlli di stile extra e generazione di Javadoc. Il build richiede circa 3 minuti. Se hai bisogno del pacchetto completo con Go SDK e operator, usa -Dfull. Questo è un ottimo esempio di come il progetto si prenda cura del tempo dei contributor.

Considerazioni sulla sicurezza

Out of the box, il registry non richiede autorizzazione, il che va bene per lo sviluppo locale ma è pericoloso su una rete aziendale. Lo strumento supporta l'integrazione OpenID Connect (OIDC). Puoi connettere Keycloak o qualsiasi altro server compatibile passando un paio di variabili di ambiente: QUARKUS_OIDC_AUTH_SERVER_URL e QUARKUS_OIDC_CLIENT_ID. La configurazione copre sia l'API REST che l'interfaccia utente.

Riepilogo: a chi dovrebbe interessare

Apicurio Registry tornerà sicuramente utile per i team che:

1. Usano attivamente Kafka e faticano a mantenere gli schemi Avro/Protobuf.
2. Vogliono automatizzare i controlli di compatibilità API (OpenAPI/AsyncAPI).
3. Cercano un'alternativa leggera a Confluent Schema Registry che non sia strettamente accoppiata a un singolo ecosistema.

Il progetto sembra vivo, la documentazione (anche quella integrata dell'API) è dettagliata, e il passaggio a Quarkus lo rende piacevole da operare. Se i tuoi microservizi hanno una situazione di "libero per tutti" per quanto riguarda i contratti — prova a dedicare un'ora e avviare questo registry. Più probabilmente di no, risolverà la maggior parte dei tuoi problemi di versioning degli schemi.