Managing Apicurio Registry content using an SDK

You can write a Apicurio Registry client application in Java, Typescript, Python, or Golang to manage artifacts stored in Apicurio Registry.

Apicurio Registry SDK

You can manage artifacts stored in Apicurio Registry by using one of the provided SDKs. You can perform any operation supported by the REST API, including create, read, update, or delete of artifacts. You can even use the Apicurio Registry SDKs to perform administrator functions, such as managing global rules or importing and exporting Apicurio Registry data.

You can use any of the following SDKs provided as part of Apicurio Registry:

  • Java

  • Typescript

  • Python

  • Golang

Java

You can access the Apicurio Registry Java SDK by adding the correct dependency to your Apache Maven project.

By default, the Apicurio Registry Java client uses a Vert.x HTTP client, and falls back to the HTTP client provided by the JDK when Vert.x is not available. You can customize the client as needed, for example, by configuring retry behavior, an HTTP proxy, or Transport Layer Security (TLS) trust options.

Typescript

You can access the Apicurio Registry Typescript SDK by adding the correct dependency to your application’s package.json file (assumes a node.js application).

Python

You can access the Apicurio Registry Python SDK by adding the correct dependency to your python project (assumes you are using pypi).

Golang

You can access the Apicurio Registry Golang SDK by adding the correct dependency to your project.

Additional resources

Writing Apicurio Registry SDK applications

You can write a client application to manage artifacts stored in Apicurio Registry by using one of the Apicurio Registry SDKs.

Prerequisites

  • Apicurio Registry is installed and running in your environment.

  • You have created a Maven project for your Java client application. For more details, see Apache Maven.

Procedure

  1. Add the following dependency to your Maven project:

    <dependency>
    <groupId>io.apicurio</groupId>
    <artifactId>apicurio-registry-java-sdk</artifactId>
    <version>${apicurio-registry.version}</version>
</dependency>

  2. Create the Apicurio Registry client as follows:

    import io.apicurio.registry.client.RegistryClientFactory;
import io.apicurio.registry.client.common.RegistryClientOptions;
import io.apicurio.registry.rest.client.RegistryClient;
import io.vertx.core.Vertx;

public class ClientExample {

    public static void main(String[] args) throws Exception {
        // Create a registry client
        Vertx vertx = Vertx.vertx();
        RegistryClientOptions options = RegistryClientOptions
                .create("https://my-registry.my-domain.com", vertx);
        RegistryClient client = RegistryClientFactory.create(options);

        // Use client here

        vertx.close();
    }
}
    The registry URL

    If you specify an example Apicurio Registry URL of https://my-registry.my-domain.com, the client automatically appends /apis/registry/v3.

    The Vertx object

    Create a new Vertx object that the client uses for HTTP requests, so that you control its lifecycle.

    The registry client

    For more options when creating a Apicurio Registry client, see Apicurio Registry Java SDK configuration.

    Closing the client

    When you are done with the client, close the Vertx object to free its resources.

Results

When the client is created, you can use all of the operations available in the Apicurio Registry REST API in the client. For more details, see the Apicurio Registry REST API documentation.

Additional resources

Apicurio Registry Java SDK configuration

The Apicurio Registry Java client supports several configuration options, including retry behavior, HTTP proxy settings, TLS trust options, and OpenTelemetry distributed tracing.

You configure the client by calling methods on a RegistryClientOptions instance and passing it to RegistryClientFactory.create. The following methods are available:

Table 1. Apicurio Registry Java client configuration methods
Method Description

create(registryUrl), create(registryUrl, vertx)

Create client options for a registry URL, optionally with an existing Vert.x instance.

retry(), retry(enabled, maxAttempts, initialDelayMs, backoffMultiplier, maxDelayMs)

Enable retry with exponential backoff for transient network failures.

proxy(host, port), proxyAuth(username, password)

Route requests through an HTTP proxy.

trustStoreJks(path, password), trustStorePkcs12(path, password), trustStorePem(path)

Configure TLS trust for a registry served over HTTPS with custom certificates.

enableOpenTelemetry()

Enable OpenTelemetry trace context propagation.

Retry configuration

Retry is disabled by default. The no-argument retry() method enables retry with the default settings: 3 attempts, an initial delay of 250 milliseconds, a backoff multiplier of 2.0, and a maximum delay of 10 seconds. The five-argument variant gives you full control:

RegistryClientOptions options = RegistryClientOptions
        .create("http://localhost:8080", vertx)
        .retry(true, 5, 500, 2.0, 15000);
RegistryClient client = RegistryClientFactory.create(options);

The client retries transient network failures only, such as refused or reset connections, socket timeouts, and closed connections. HTTP error responses from the registry are not retried. The delay grows by the backoff multiplier after each attempt, up to the maximum delay. When all attempts fail, the client throws the original exception.

HTTP proxy configuration

To route requests through an HTTP proxy, set the proxy host and port. For proxies that require authentication, also provide credentials:

RegistryClientOptions options = RegistryClientOptions
        .create("http://localhost:8080", vertx)
        .proxy("proxy.example.com", 3128)
        .proxyAuth("proxyuser", "proxypass");
RegistryClient client = RegistryClientFactory.create(options);

The proxy configuration applies to registry API calls and to OAuth token endpoint calls. When you supply your own Vert.x WebClient with the customWebClient option, the client uses that WebClient unchanged, so you must configure the proxy on the WebClient yourself.

The Kafka client SerDes expose the same proxy settings as configuration properties: apicurio.registry.proxy.host, apicurio.registry.proxy.port, apicurio.registry.proxy.username, and apicurio.registry.proxy.password. For details, see Configuring Kafka serializers/deserializers in Java clients.

TLS configuration

For a registry served over HTTPS with certificates that the default Java trust store does not trust, configure a trust store with the trustStoreJks, trustStorePkcs12, or trustStorePem method. Methods for client certificates (mutual TLS), including keystoreJks and keystorePkcs12, are also available.

OpenTelemetry distributed tracing

The Apicurio Registry Java SDK supports optional OpenTelemetry trace context propagation. When enabled, W3C trace context headers (traceparent and tracestate) are injected into every HTTP request made to Apicurio Registry, providing end-to-end distributed tracing across your services and the registry.

Enabling tracing

Call enableOpenTelemetry() when building the client options:

RegistryClientOptions options = RegistryClientOptions.create()
        .registryUrl("http://localhost:8080")
        .enableOpenTelemetry();
RegistryClient client = RegistryClientFactory.create(options);
Required dependency

The opentelemetry-api library must be on the classpath. Add it to your project if it is not already provided transitively:

<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api</artifactId>
    <version>${opentelemetry.version}</version>
</dependency>
Runtime behavior

When an OpenTelemetry SDK is initialized in your application (for example, through the OpenTelemetry Java agent or the Quarkus OpenTelemetry extension), the Apicurio Registry SDK participates in the active trace. If no OpenTelemetry SDK is configured, the behavior is a no-op and no trace headers are added.

This feature also applies to the Apicurio Registry Kafka client serializers/deserializers (SerDes), which use the SDK internally to communicate with Apicurio Registry. See Validating schemas using Kafka client serializers/deserializers in Java clients for SerDes-specific configuration.
Additional resources