Como trazer ordem para APIs e schemas com o Apicurio Registry

Imagine que você está construindo uma arquitetura de microsserviços onde os dados fluem através do Kafka ou requisições REST. Você acumulou uma dúzia de schemas Avro, várias especificações OpenAPI e alguns arquivos Protobuf. Em algum momento, uma equipe atualiza um schema de mensagem e o sistema de outra equipe "quebra" porque não ficou sabendo das mudanças a tempo. Soa familiar? Você poderia, é claro, armazenar schemas no Git e copiá-los entre projetos, mas isso rapidamente se transforma em caos.

Encontrei o Apicurio Registry enquanto procurava uma alternativa às soluções padrão de gerenciamento de contratos de API. É um projeto sandbox da CNCF que resolve um ponto específico de dor: fornece um repositório centralizado para suas APIs e schemas.

Por que se bother se você tem o Git

O recurso principal não é apenas colocar um arquivo "na prateleira" — é sobre como o registro funciona com esses dados. O Apicurio Registry pode validar a compatibilidade de schemas em tempo real. Quando um serviço produtor tenta publicar uma nova versão de schema, o registro pode bloquear a atualização se ela quebrar a compatibilidade com versões anteriores. Você captura o erro antes que dados incorretos acabem na fila de mensagens.

Além disso, o projeto lida com o versionamento para você. Cada schema recebe um ciclo de vida claro, e os consumidores sempre sabem qual versão usar.

O que está por baixo do capô e como funciona

Os desenvolvedores do Apicurio escolheram Quarkus como base, tornando a ferramenta rápida e leve. Mas a parte mais interessante é a flexibilidade nas opções de armazenamento. Antes, havia um binário separado para cada banco de dados, e na versão 3.0 eles mudaram para um único artefato. Agora você só precisa definir a variável de ambiente APICURIO_STORAGE_KIND e escolher entre as seguintes opções:

• SQL — a escolha clássica. O padrão é H2 (conveniente para testes), mas em produção é melhor usar PostgreSQL ou SQL Server.
• KafkaSQL — armazena dados diretamente em tópicos Kafka. Isso é útil se você não quer adicionar um banco de dados relacional separado à sua infraestrutura e já tem um cluster Kafka.
• GitOps — uma opção para quem quer gerenciamento declarativo.

Para quem usa Kubernetes, há um operador pronto para uso. As atualizações vêm através dos canais OLM, então manter uma versão atualizada no seu cluster não será muito doloroso.

Como experimentar

O jeito mais rápido de dar uma olhada no sistema é executar a imagem Docker pronta. Mas é importante lembrar: a UI foi movida para um container separado.

Para executar o servidor em si:

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

E para a interface:

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

Depois disso, o painel de gerenciamento estará disponível em localhost:8888, e a documentação da própria API do registro estará em localhost:8080/apis.

Se você quiser fazer deploy de uma configuração completa com PostgreSQL para testes adequados, o jeito mais fácil é criar um arquivo 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

Níveis de build para os impacientes

Se você decidir mergulhar no código-fonte e construir o projeto você mesmo, o projeto oferece três "níveis" de build. Isso economiza muito tempo.

Usando a flag -Dlocal, você constrói apenas o núcleo do servidor e o SDK Java sem verificações de estilo extras e geração de Javadoc. O build leva cerca de 3 minutos. Se você precisa do pacote completo com SDK Go e operadores, use -Dfull. Este é um ótimo exemplo de como o projeto se preocupa com o tempo dos contribuidores.

Considerações de segurança

Fora da caixa, o registro não requer autorização, o que é fine para desenvolvimento local mas perigoso em uma rede corporativa. A ferramenta suporta integração com OpenID Connect (OIDC). Você pode conectar o Keycloak ou qualquer outro servidor compatível passando algumas variáveis de ambiente: QUARKUS_OIDC_AUTH_SERVER_URL e QUARKUS_OIDC_CLIENT_ID. A configuração cobre tanto a API REST quanto a interface do usuário.

Resumo: quem deveria dar uma olhada

O Apicurio Registry certamente será útil para equipes que:

1. Usam ativamente o Kafka e lutam para manter schemas Avro/Protobuf.
2. Querem automatizar verificações de compatibilidade de API (OpenAPI/AsyncAPI).
3. Estão procurando uma alternativa leve ao Confluent Schema Registry que não esteja acoplada a um único ecossistema.

O projeto parece vivo, a documentação (inclusive a documentação da API integrada) é detalhada, e a mudança para o Quarkus torna o operação agradável. Se seus microsserviços têm uma situação de "cada um por si" quando se trata de contratos — tente dedicar uma hora e subir esse registro. É mais provável do que não que ele resolva a maioria dos seus problemas de versionamento de schemas.