include::{mod-loc}shared/all-attributes.adoc[]

// assembly-using-the-registry-client
[id="using-the-registry-sdk_{context}"]
:_mod-docs-content-type: ASSEMBLY
= Managing {registry} content using an SDK

[role="_abstract"]
You can write a {registry} client application in Java, Typescript, Python, or Golang to manage artifacts stored in {registry}.

* xref:registry-sdk-intro_{context}[]
* xref:writing-registry-sdk_{context}[]
* xref:registry-sdk-config_{context}[]

//INCLUDES


// Metadata created by nebel

// con-registry-sdk-intro
[id="registry-sdk-intro_{context}"]
:_mod-docs-content-type: CONCEPT
== {registry} SDK

[role="_abstract"]
You can manage artifacts stored in {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 {registry} SDKs to perform administrator functions, such as managing global rules or importing and exporting {registry} data.

You can use any of the following SDKs provided as part of {registry}:

- Java
- Typescript
- Python
- Golang

**Java**

You can access the {registry} Java SDK by adding the correct dependency to your Apache Maven project.
For more details, see xref:writing-registry-sdk_registry[].

The {registry} client is implemented by using the HTTP client provided by the JDK. You can customize the client as needed, for example, by adding custom headers or enabling configuration options for Transport Layer Security (TLS) authentication.
For more details, see xref:registry-sdk-config_registry[].

**Typescript**

You can access the {registry} Typescript SDK by adding the correct dependency to your application's `package.json`
file (assumes a node.js application):

https://www.npmjs.com/package/@apicurio/apicurio-registry-sdk

**Python**

You can access the {registry} Python SDK by adding the correct dependency to your python project (assumes you
are using pypi):

https://pypi.org/project/apicurioregistrysdk/

**Golang**

You can access the {registry} Golang SDK by adding the correct dependency to your project:

https://github.com/Apicurio/apicurio-registry/tree/main/go-sdk




// Metadata created by nebel
// ParentAssemblies: assemblies/getting-started/as_installing-the-registry.adoc

// proc-writing-registry-sdk
[id="writing-registry-sdk_{context}"]
:_mod-docs-content-type: PROCEDURE
== Writing {registry} SDK applications

[role="_abstract"]
You can write a client application to manage artifacts stored in {registry} by using one of the {registry} SDKs.

.Prerequisites
* {registry} is installed and running in your environment.
* You have created a Maven project for your Java client application. For more details, see https://maven.apache.org/index.html[Apache Maven].

.Procedure
. Add the following dependency to your Maven project:
+
[source,xml,subs="+quotes,attributes"]
----
<dependency>
    <groupId>io.apicurio</groupId>
    <artifactId>apicurio-registry-java-sdk</artifactId>
    <version>${apicurio-registry.version}</version>
</dependency>
----

. Create the {registry} client as follows:
+
[source,java,subs="+quotes,attributes"]
----
import io.vertx.core.Vertx;public class ClientExample {

    public static void main(String[] args) throws Exception {
        // Create a registry client
        String registryUrl = "https://my-registry.my-domain.com/apis/registry/v3"; <1>
        Vertx vertx = Vertx.vertx(); <2>
        VertXRequestAdapter vertXRequestAdapter = new VertXRequestAdapter(vertx);
        vertXRequestAdapter.setBaseUrl(REGISTRY_URL);

        RegistryClient client = new RegistryClient(vertXRequestAdapter); <3>

        // Use client here

        vertx.close(); <4>
    }
}
----
+
<1> If you specify an example {registry} URL of `\https://my-registry.my-domain.com`, the client automatically appends `/apis/registry/v3`.
<2> Create a new Vertx object (needed by the VertxRequestAdapter)
<3> For more options when creating a {registry} client, see xref:registry-sdk-config_registry[].
<4> When you are done with the client, close the Vertx object to free its resources.

.Result
When the client is created, you can use all of the operations available in the {registry} REST API in the client. For more details, see the {registry-rest-api}.

[role="_additional-resources"]
.Additional resources
* https://github.com/Apicurio/apicurio-registry/tree/main/examples[Apicurio Registry REST client demonstration]
* {kafka-client-serdes}



// Metadata created by nebel
// ParentAssemblies: assemblies/getting-started/assembly-using-the-registry-sdk.adoc

// ref-registry-sdk-config
[id="registry-sdk-config_{context}"]
:_mod-docs-content-type: REFERENCE
== {registry} Java SDK configuration

[role="_abstract"]
The {registry} Java client supports several configuration options, including client factory settings, custom headers, TLS authentication, and OpenTelemetry distributed tracing.

.{registry} Java client configuration options
[%header,cols="1,2,1"]
|===
|Option
|Description
|Arguments
|Plain client
|Connects to a running {registry} with no additional configuration.
|`baseUrl`
|Client with custom configuration
|{registry} client that uses the configuration that you provide.
|`baseUrl`, `Map<String Object> configs`
|Client with custom configuration and authentication
|Accepts a map containing custom configuration and an authentication server. You can use this option to add custom headers and authenticate requests.
|`baseUrl, Map<String Object> configs, Auth auth`
|===

**Custom header configuration**

To configure custom headers, add the `apicurio.registry.request.headers` prefix to the `configs` map key. For example, a `configs` map key of `apicurio.registry.request.headers.Authorization` with a value of `Basic: YWxhZGRpbjpvcGVuc2VzYW1` sets the `Authorization` header with the same value.

**TLS configuration properties**

The following properties configure Transport Layer Security (TLS) authentication for the {registry} Java client:

* `apicurio.registry.request.ssl.truststore.location`
* `apicurio.registry.request.ssl.truststore.password`
* `apicurio.registry.request.ssl.truststore.type`
* `apicurio.registry.request.ssl.keystore.location`
* `apicurio.registry.request.ssl.keystore.password`
* `apicurio.registry.request.ssl.keystore.type`
* `apicurio.registry.request.ssl.key.password`

**OpenTelemetry distributed tracing**

The {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 {registry}, providing end-to-end distributed tracing across your services and the registry.

Enabling tracing:: Call `enableOpenTelemetry()` when building the client options:
+
[source,java]
----
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:
+
[source,xml,subs="+quotes,attributes"]
----
<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 {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.

NOTE: This feature also applies to the {registry} Kafka client serializers/deserializers (SerDes), which use the SDK internally to communicate with {registry}. See {kafka-client-serdes} for SerDes-specific configuration.


[role="_additional-resources"]
.Additional resources
* {kafka-client-serdes}


