From 8bae786f8aa7b8882f2ba353d9ba2745ef9fc631 Mon Sep 17 00:00:00 2001 From: Carles Arnal Date: Thu, 29 Oct 2020 19:55:52 +0100 Subject: [PATCH] Add registry client documentation (#955) * Add registry client documentation * Improve custom header docs * Update con-registry-client.adoc * Update ref-registry-client.adoc * Update proc-writing-registry-client.adoc * Improve rest client docs * Address comments Co-authored-by: Eric Wittmann --- .../getting-started/con-registry-client.adoc | 20 ++++++++- .../proc-writing-registry-client.adoc | 43 ++++++++++++++----- .../getting-started/ref-registry-client.adoc | 26 +++++++---- 3 files changed, 68 insertions(+), 21 deletions(-) diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-client.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-client.adoc index 750c72849e..538e7275e3 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-client.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-client.adoc @@ -3,6 +3,22 @@ [id="registry-client-intro"] = {registry} Java client overview -You can manage artifacts stored in {registry} using a Java client application. You can create, read, update, or delete artifacts stored in the registry using the {registry} Java client classes... +You can manage artifacts stored in {registry} using a Java client application. You can create, read, update, or delete artifacts stored +in the registry using the {registry} Java client classes. -More TBD +You can access the {registry} Java client by adding the proper dependency to your project, see xref:writing-registry-client[]. + +The {registry} client is autocloseable and is implemented using Retrofit and OkHttp as base libraries. This gives the user the ability to customize its +usage by, for example, adding custom headers or enabling TLS auth support. + +== Enabling TLS support in the client + +You can configure TLS authentication using the following properties: + +* 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 diff --git a/docs/modules/ROOT/partials/getting-started/proc-writing-registry-client.adoc b/docs/modules/ROOT/partials/getting-started/proc-writing-registry-client.adoc index f6c61def2c..4254a03c55 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-writing-registry-client.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-writing-registry-client.adoc @@ -4,28 +4,49 @@ [id="writing-registry-client"] = Writing a {registry} client application -This section explains how to manage artifacts stored in {registry} using a Java client application... - -More TBD +This section explains how to manage artifacts stored in {registry} using a Java client application. .Prerequisites - * See {registry-overview} -* {registry} must be installed and running in your environment +* {registry} must be installed and running in your environment. +* Add the following dependency to your Maven project: -.Procedure +[source,xml,subs="+quotes,attributes"] +---- + + io.apicurio + apicurio-registry-rest-client + ${apicurio-registry.version} + +---- -. Enter step one here. +.Procedure +. Create a registry client + [source,java,subs="+quotes,attributes"] ---- -Insert client code sample here <1> -... +public class ClientExample { + + private static final RegistryRestClient client; + + public static void main(String[] args) throws Exception { + // Create a Service Registry client + String registryUrl = "http://localhost:8080/api/"; + RegistryRestClient client = RegistryRestClientFactory.create(registryUrl); <1> + } +} ---- -<1> Describe the client code sample here +<1> For more options on how to create a {registry} client, see {registry-client-types}. + +. Once created, all the operations from the {registry} REST API are available through the client. For details about the available +operations, see the REST API documentation. + + +The {registry} Java client extends the interface Autocloseable. .Additional resources -* For an example Java client application, see https://github.com/Apicurio/apicurio-registry-demo. +* For more examples on how to use or customize the {registry} client see https://github.com/Apicurio/apicurio-registry-examples/blob/master/rest-client + ifdef::rh-service-registry[] * For details on how to use the {registry} Kafka client serializer/deserializer for Apache Avro in AMQ Streams producer and consumer applications, see link:https://access.redhat.com/documentation/en-us/red_hat_amq/{amq-version}/html/using_amq_streams_on_openshift/service-registry-str[Using AMQ Streams on Openshift]. diff --git a/docs/modules/ROOT/partials/getting-started/ref-registry-client.adoc b/docs/modules/ROOT/partials/getting-started/ref-registry-client.adoc index 881361d900..4109ffc7f7 100644 --- a/docs/modules/ROOT/partials/getting-started/ref-registry-client.adoc +++ b/docs/modules/ROOT/partials/getting-started/ref-registry-client.adoc @@ -3,15 +3,25 @@ [id="registry-client-types"] = {registry} Java client reference -The {registry} Java client includes the following... +The {registry} Java client includes the following configuration options, based on the client factory. -More TBD - -.{registry} Java client types -[%header,cols=2*] +.{registry} Java client options +[%header,cols=3*] |=== -|Type +|Option |Description -|`TBD` -| TBD +|Arguments +|Plain Client +|Basic REST client used to interact with a running registry. +|baseUrl +|Custom HTTP client +|Registry client using an OkHttpClient provided by the user. +|baseUrl, okhttpClient +|Custom Configuration +|Registry client that accepts a map containing custom configuration. This is useful, for example, to add custom headers to the calls. +|baseUrl, Map configs |=== + + +In order to configure custom headers, the prefix *apicurio.registry.request.headers* must be added to the configs map key, for example, a key *apicurio.registry.request.headers.Authorization* with value Basic: xxxxx would result in a header of *Authorization* with value Basic: xxxxx. +