Schema Registry Client for Java

Cliente Java leve para a API REST compatível com Confluent Schema Registry. Este repositório é uma biblioteca cliente: ele não implementa nem hospeda um Schema Registry.

Recursos

• listar subjects;
• ler a versão mais recente ou uma versão específica;
• registrar schemas Avro, JSON Schema ou Protobuf;
• testar compatibilidade com a versão mais recente;
• autenticação Basic (Confluent Cloud) ou Bearer;
• sem dependência de Kafka: usa apenas java.net.http.HttpClient e Jackson;
• exceções HTTP com status e corpo da resposta para diagnóstico.

Requisitos

• Java 25;
• Maven 3.9+;
• endpoint de um Schema Registry compatível com a API do Confluent.

Instalação

O pacote está publicado no GitHub Packages. No projeto consumidor, configure o repositório:

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/gabivech/schema-registry-client-java</url>
    </repository>
</repositories>

Depois adicione a dependência:

<dependency>
    <groupId>io.github.gabivech</groupId>
    <artifactId>schema-registry-client</artifactId>
    <version>0.1.0</version>
</dependency>

Para repositórios privados, crie no ~/.m2/settings.xml um servidor github com um token que tenha read:packages. Não coloque tokens no pom.xml, no código ou no Git.

Uso

var client = ConfluentSchemaRegistryClient.builder(
        URI.create("https://registry.example.com"))
    .basicAuth(System.getenv("SCHEMA_REGISTRY_KEY"), System.getenv("SCHEMA_REGISTRY_SECRET"))
    .build();

var latest = client.getLatestSchema("orders-value");
String schemaText = """
    {"type":"record","name":"Order","fields":[{"name":"id","type":"string"}]}
    """;
var compatibility = client.testCompatibility(
    "orders-value",
    schemaText,
    SchemaType.AVRO
);

if (compatibility.compatible()) {
    client.register("orders-value", schemaText, SchemaType.AVRO);
}

Autenticação e configuração

Use exatamente uma forma de autenticação. Sem uma chamada de autenticação, o cliente envia requisições anônimas.

var client = ConfluentSchemaRegistryClient.builder(URI.create("https://registry.example/api/"))
    .bearerToken(System.getenv("SCHEMA_REGISTRY_TOKEN"))
    .timeout(Duration.ofSeconds(15))
    .build();

timeout controla tanto o timeout de conexão do cliente padrão quanto o timeout de cada requisição. A URL base deve ser HTTP(S) absoluta e pode conter um caminho, como /api/; esse caminho é preservado nas chamadas. basicAuth e bearerToken não podem ser usados juntos.

Tratamento de erros

Respostas não 2xx lançam SchemaRegistryException. Ela expõe statusCode() e responseBody() para permitir tratamento por status:

try {
    client.getLatestSchema("orders-value");
} catch (SchemaRegistryException exception) {
    if (exception.statusCode() == 404) {
        // subject ainda não existe
    } else {
        throw exception;
    }
}

Subjects são codificados corretamente no caminho da URL, inclusive quando contêm espaços ou barras.

Build

mvn --batch-mode clean test

Publicar no GitHub Packages

O workflow em .github/workflows/publish.yml publica automaticamente quando uma tag v* é enviada ou quando a ação é executada manualmente.

Para publicar uma versão:

git tag v0.1.0
git push origin v0.1.0

O workflow usa o GITHUB_TOKEN fornecido pelo GitHub Actions; nenhuma credencial deve ser commitada. Para consumir o pacote, configure no ~/.m2/settings.xml um servidor com id github e um token com permissão read:packages, além de adicionar o repositório Maven do GitHub ao projeto consumidor.

Integração futura com o MCP Kafka

O kafka-mcp-java pode usar esta biblioteca para expor ferramentas como list_schemas, get_schema e check_schema_compatibility, sem misturar o cliente HTTP do registry com o servidor MCP.