How to bring order to APIs and schemas with Apicurio Registry

Imagine you're building a microservices architecture where data flows through Kafka or REST requests. You've accumulated a dozen Avro schemas, several OpenAPI specifications, and a handful of Protobuf files. At some point, one team updates a message schema and another team's system "breaks" because they didn't learn about the changes in time. Sound familiar? You could, of course, store schemas in Git and copy them between projects, but that quickly turns into chaos.

I came across Apicurio Registry while looking for an alternative to standard API contract management solutions. It's a CNCF sandbox project that solves one specific pain point: it provides a centralized repository for your APIs and schemas.

Why bother if you have Git

The key feature isn't just about putting a file "on the shelf" — it's about how the registry works with that data. Apicurio Registry can validate schema compatibility on the fly. When a producer service tries to publish a new schema version, the registry can block the update if it breaks backward compatibility. You catch the error before incorrect data ends up in the message queue.

Additionally, the project handles versioning for you. Each schema gets a clear lifecycle, and consumers always know which version to use.

What's under the hood and how it works

The Apicurio developers chose Quarkus as the foundation, making the tool fast and lightweight. But the most interesting part is the flexibility in storage options. Previously, there was a separate binary for each database, and in version 3.0 they switched to a single artifact. Now you just set the APICURIO_STORAGE_KIND environment variable and choose from the following options:

• SQL — the classic choice. Defaults to H2 (convenient for testing), but in production you're better off using PostgreSQL or SQL Server.
• KafkaSQL — stores data directly in Kafka topics. This is handy if you don't want to add a separate relational database to your infrastructure and you already have a Kafka cluster.
• GitOps — an option for those who want declarative management.

For those using Kubernetes, there's a ready-made operator. Updates come through OLM channels, so keeping an up-to-date version in your cluster won't be too painful.

How to try it out

The fastest way to take a look at the system is to run the ready-made Docker image. But it's important to remember: the UI was moved to a separate container.

To run the server itself:

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

And for the interface:

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

After that, the management dashboard will be available at localhost:8888, and the documentation for the registry's own API will be at localhost:8080/apis.

If you want to deploy a full setup with PostgreSQL for proper testing, the easiest way is to whip up a Docker Compose file:

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 for the impatient

If you decide to dig into the source code and build the project yourself, the project offers three build "tiers." This saves a lot of time.

Using the -Dlocal flag, you build only the server core and Java SDK without extra style checks and Javadoc generation. The build takes about 3 minutes. If you need the full package with Go SDK and operators, use -Dfull. This is a great example of how the project cares about contributors' time.

Security considerations

Out of the box, the registry doesn't require authorization, which is fine for local development but dangerous on a corporate network. The tool supports OpenID Connect (OIDC) integration. You can connect Keycloak or any other compatible server by passing a couple of environment variables: QUARKUS_OIDC_AUTH_SERVER_URL and QUARKUS_OIDC_CLIENT_ID. The configuration covers both the REST API and the user interface.

Summary: who should take a look

Apicurio Registry will definitely come in handy for teams that:

1. Actively use Kafka and struggle with maintaining Avro/Protobuf schemas.
2. Want to automate API compatibility checks (OpenAPI/AsyncAPI).
3. Are looking for a lightweight alternative to Confluent Schema Registry that isn't tightly coupled to a single ecosystem.

The project looks alive, the documentation (even the built-in API documentation) is detailed, and the switch to Quarkus makes it pleasant to operate. If your microservices have a "free for all" situation when it comes to contracts — try spending an hour and spinning up this registry. More likely than not, it will solve most of your schema versioning problems.