Hoe breng je orde in API's en schemas met Apicurio Registry

Stel je voor dat je een microservices-architectuur bouwt waarbij data door Kafka of REST-requests stroomt. Je hebt een dozijn Avro-schemas verzameld, verschillende OpenAPI-specificaties en een handvol Protobuf-bestanden. Op een gegeven moment past het ene team een berichtenschema aan en "breekt" het systeem van een ander team omdat ze niet op tijd op de hoogte waren van de wijzigingen. Herkenbaar? Je kunt natuurlijk schemas in Git opslaan en ze tussen projecten kopiëren, maar dat verandert al snel in chaos.

Ik kwam Apicurio Registry tegen tijdens het zoeken naar een alternatief voor standaard API-contractbeheer-oplossingen. Het is een CNCF sandbox-project dat één specifiek pijnpunt oplost: het biedt een gecentraliseerde repository voor je API's en schemas.

Waarom de moeite als je Git hebt

De belangrijkste functie gaat niet alleen over het "op de plank zetten" van een bestand — het gaat om hoe de registry met die data werkt. Apicurio Registry kan schema-compatibiliteit real-time valideren. Wanneer een producer-service probeert een nieuwe schema-versie te publiceren, kan de registry de update blokkeren als deze de backward compatibility verbreekt. Je pakt de fout op voordat incorrecte data in de message queue belandt.

Bovendien regelt het project het versiebeheer voor je. Elk schema krijgt een duidelijke levenscyclus, en consumers weten altijd welke versie ze moeten gebruiken.

Wat zit er onder de motorkap en hoe het werkt

De Apicurio-ontwikkelaars kozen Quarkus als fundament, waardoor het tool snel en lichtgewicht is. Maar het meest interessante deel is de flexibiliteit in opslagopties. Voorheen was er een apart binair bestand voor elke database, en in versie 3.0 schakelden ze over naar een enkel artifact. Nu stel je gewoon de APICURIO_STORAGE_KIND environment variable in en kies je uit de volgende opties:

• SQL — de klassieke keuze. Standaard H2 (handig voor testen), maar in productie kun je beter PostgreSQL of SQL Server gebruiken.
• KafkaSQL — slaat data direct op in Kafka-topics. Dit is handig als je geen aparte relationele database aan je infrastructuur wilt toevoegen en je al een Kafka-cluster hebt.
• GitOps — een optie voor wie declaratief beheer wil.

Voor wie Kubernetes gebruikt, is er een kant-en-klare operator. Updates komen via OLM-kanalen, dus een up-to-date versie in je cluster houden zal niet al te pijnlijk zijn.

Hoe het uit te proberen

De snelste manier om het systeem te bekijken is door de kant-en-klare Docker-image te draaien. Maar het is belangrijk om te onthouden: de UI is verplaatst naar een aparte container.

Om de server zelf te draaien:

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

En voor de interface:

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

Daarna is het management dashboard beschikbaar op localhost:8888, en de documentatie voor de eigen API van de registry op localhost:8080/apis.

Als je een complete setup met PostgreSQL wilt voor goed testen, is de makkelijkste manier om een Docker Compose-file in elkaar te draaien:

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

Build-tiers voor de ongeduldigen

Als je besluit om in de broncode te duiken en het project zelf te bouwen, biedt het project drie build-"tiers". Dit bespaart veel tijd.

Met de -Dlocal vlag bouw je alleen de serverkern en Java SDK zonder extra style checks en Javadoc-generatie. De build duurt ongeveer 3 minuten. Als je het volledige pakket met Go SDK en operators nodig hebt, gebruik je -Dfull. Dit is een goed voorbeeld van hoe het project omgaat met de tijd van contributors.

Beveiligingsoverwegingen

Out of the box vereist de registry geen autorisatie, wat prima is voor lokale ontwikkeling maar gevaarlijk op een bedrijfsnetwerk. Het tool ondersteunt OpenID Connect (OIDC) integratie. Je kunt Keycloak of elke andere compatibele server aansluiten door een paar environment variables door te geven: QUARKUS_OIDC_AUTH_SERVER_URL en QUARKUS_OIDC_CLIENT_ID. De configuratie dekt zowel de REST API als de user interface.

Samenvatting: voor wie is het de moeite waard

Apicurio Registry komt zeker van pas voor teams die:

1. Actief Kafka gebruiken en moeite hebben met het onderhouden van Avro/Protobuf-schemas.
2. API-compatibiliteitscontroles willen automatiseren (OpenAPI/AsyncAPI).
3. Op zoek zijn naar een lichtgewicht alternatief voor Confluent Schema Registry dat niet gekoppeld is aan één ecosysteem.

Het project leeft, de documentatie (zelfs de ingebouwde API-documentatie) is gedetailleerd, en de switch naar Quarkus maakt het prettig in gebruik. Als je microservices een "free for all"-situatie hebben als het gaat om contracten — probeer eens een uur te besteden aan het draaien van deze registry. Waarschijnlijk lost het het merendeel van je schema-versieeringsproblemen op.