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 <[email protected]>
Apicurio · Oct 29, 2020 · 8bae786 · 8bae786
1 parent fb80f34
commit 8bae786
Show file tree

Hide file tree

Showing 3 changed files with 68 additions and 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
@@ -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
@@ -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"]
+----
+<dependency>
+    <groupId>io.apicurio</groupId>
+    <artifactId>apicurio-registry-rest-client</artifactId>
+    <version>${apicurio-registry.version}</version>
+</dependency>
+----
 
-. 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
@@ -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<String, Object> 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.
+