Apicurio Registry User Guide

Procedure

1. On the Artifacts tab, browse the list of artifacts stored in Apicurio Registry, or enter a search string to find an artifact. You can select from the list to search by specific criteria such as name, group, labels, or global ID.

   Figure 3.1. Artifacts in Apicurio Registry web console

   

2. Click an artifact to view the following details:

   • Overview: Displays artifact version metadata such as artifact name, artifact ID, global ID, content ID, labels, properties, and so on. Also displays rules for validity and compatibility that you can configure for artifact content.
   • Documentation (OpenAPI and AsyncAPI only): Displays automatically-generated REST API documentation.
   • Content: Displays a read-only view of the full artifact content. For JSON content, you can click JSON or YAML to display your preferred format.
   • References: Displays a read-only view of all artifacts referenced by this artifact. You can also click View artifacts that reference this artifact.
3. If additional versions of this artifact have been added, you can select them from the Version list in page header.
4. To save the artifact contents to a local file, for example, my-openapi.json or my-protobuf-schema.proto, and click Download at the end of the page.

Procedure

1. On the Artifacts tab, click Upload artifact, and specify the following details:

   • Group & ID: Use the default empty settings to automatically generate an artifact ID and add the artifact to the default artifact group. Alternatively, you can enter an optional artifact group name or ID.
   • Type: Use the default Auto-Detect setting to automatically detect the artifact type, or select the artifact type from the list, for example, Avro Schema or OpenAPI. You must manually select the Kafka Connect Schema artifact type, which cannot be automatically detected.

   • Artifact: Specify the artifact location using either of the following options:

     • From file: Click Browse, and select a file, or drag and drop a file. For example, my-openapi.json or my-schema.proto. Alternatively, you can enter the file contents in the text box.
     • From URL: Enter a valid and accessible URL, and click Fetch. For example: https://petstore3.swagger.io/api/v3/openapi.json.

2. Click Upload and view the artifact details:

   • Overview: Displays artifact version metadata such as artifact name, artifact ID, global ID, content ID, labels, properties, and so on. Also displays rules for validity and compatibility that you can configure for artifact content.
   • Documentation (OpenAPI and AsyncAPI only): Displays automatically-generated REST API documentation.
   • Content: Displays a read-only view of the full artifact content. For JSON content, you can click JSON or YAML to display your preferred format.

   • References: Displays a read-only view of all artifacts referenced by this artifact. You can also click View artifacts that reference this artifact. You can add artifact references using the Apicurio Registry Maven plug-in or REST API only.

     The following example shows an example OpenAPI artifact:

     Figure 3.2. Artifact details in Apicurio Registry web console

     

3. On the Overview tab, click the Edit pencil icon to edit artifact metadata such as name or description.

   You can also enter an optional comma-separated list of labels for searching, or add key-value pairs of arbitrary properties associated with the artifact. To add properties, perform the following steps:

   1. Click Add property.
   2. Enter the key name and the value.
   3. Repeat the first two steps to add multiple properties.
   4. Click Save.
4. To save the artifact contents to a local file, for example, my-protobuf-schema.proto or my-openapi.json, click Download at the end of the page.
5. To add a new artifact version, click Upload new version in the page header, and drag and drop or click Browse to upload the file, for example, my-avro-schema.json or my-openapi.json.

6. To delete an artifact, click Delete in the page header.

   Warning

   Deleting an artifact deletes the artifact and all of its versions, and cannot be undone.

Procedure

1. On the Artifacts tab, browse the list of artifacts in Apicurio Registry, or enter a search string to find an artifact. You can select from the list to search by specific criteria such as artifact name, group, labels, or global ID.
2. Click an artifact to view its version details and content rules.

3. In Artifact-specific rules, click Enable to configure a validity, compatibility, or integrity rule for artifact content, and select the appropriate rule configuration from the list. For example, for Validity rule, select Full.

   Figure 3.3. Artifact content rules in Apicurio Registry web console

   
4. To access global rules, click the Global rules tab. Click Enable to configure global validity, compatibility, or integrity rules for all artifact content, and select the appropriate rule configuration from the list.
5. To disable an artifact rule or global rule, click the trash icon next to the rule.

Procedure

1. On the Artifacts tab, browse the list of artifacts stored in Apicurio Registry, or enter a search string to find a specific OpenAPI artifact. You can select from the list to search by criteria such as name, group, labels, or global ID.
2. Click the OpenAPI artifact in the list to view its details.

3. In the Version metadata section, click Generate client SDK, and configure the following settings in the dialog:

   • Language: Select the programming language in which to generate the client SDK, for example, Java.
   • Generated client class name: Enter the class name for the client SDK, for example, MyJavaClientSDK.
   • Generated client package name: Enter the package name for the client SDK, for example, io.my.example.sdk

4. Click Show advanced settings to configure optional comma-separated lists of path patterns to include or exclude:

   • Include path patterns: Enter specific paths to include when generating the client SDK, for example, **/.*, **/my-path/*. If this field is empty, all paths are included.

   • Exclude path patterns: Enter specific paths to exclude when generating the client SDK, for example, **/my-other-path/*. If this field is empty, no paths are excluded.

     Figure 3.4. Generate a Java client SDK in Apicurio Registry web console

     
5. When you have configured the settings in the dialog, click Generate and download.
6. Enter a file name for the client SDK in the dialog, for example, my-client-java.zip, and click Save to download.

Procedure

1. On the Artifacts tab, browse the list of artifacts stored in Apicurio Registry, or enter a search string to find the artifact. You can select from the list to search by criteria such as name, group, labels, or global ID.
2. Click the artifact that you want to reassign.
3. In the Version metadata section, click the pencil icon next to the Owner field.
4. In the New owner field, select or enter an account name.
5. Click Change owner.

Procedure

1. In the Apicurio Registry web console, click the Settings tab.

2. Select the settings that you want to configure for this Apicurio Registry instance:

   Table 3.1. Authentication settings

   Setting	Description
   HTTP basic authentication	Displayed only when authentication is already enabled. When selected, Apicurio Registry users can authenticate using HTTP basic authentication, in addition to OAuth. Not selected by default.

   Table 3.2. Authorization settings

   Setting	Description
   Anonymous read access	Displayed only when authentication is already selected. When selected, Apicurio Registry grants read-only access to requests from anonymous users without any credentials. This setting is useful if you want to use this instance to publish schemas or APIs externally. Not selected by default.
   Artifact owner-only authorization	Displayed only when authentication is already enabled. When selected, only the user who created an artifact can modify that artifact. Not selected by default.
   Artifact group owner-only authorization	Displayed only when authentication is already enabled and Artifact owner-only authorization is selected. When selected, only the user who created an artifact group has write access to that artifact group, for example, to add or remove artifacts in that group. Not selected by default.
   Authenticated read access	Displayed only when authentication is already enabled. When selected, Apicurio Registry grants at least read-only access to requests from any authenticated user regardless of their user role. Not selected by default.

   Table 3.3. Compatibility settings

   Setting	Description
   Legacy ID mode (compatibility API)	When selected, the Confluent Schema Registry compatibility API uses globalId instead of contentId as an artifact identifier. This setting is useful when migrating from legacy Apicurio Registry instances based on the v1 Core Registry API. Not selected by default.

   Table 3.4. Web console settings

   Setting	Description
   Download link expiry	The number of seconds that a generated link to a .zip download file is active before expiring for security reasons, for example, when exporting artifact data from the instance. Defaults to 30 seconds.
   UI read-only mode	When selected, the Apicurio Registry web console is set to read-only, preventing create, read, update, or delete operations. Changes made using the Core Registry API are not affected by this setting. Not selected by default.

   Table 3.5. Additional properties

   Setting	Description
   Delete artifact version	When selected, users are permitted to delete artifact versions in this instance by using the Core Registry API. Not selected by default.

Procedure

1. In the web console for the source Apicurio Registry instance, view the Artifacts tab.
2. Click the options icon (three vertical dots) next to Upload artifact, and select Download all artifacts (.zip file) to export the data for this Apicurio Registry instance to a .zip download file.
3. In the the web console for the target Apicurio Registry instance, view the Artifacts tab.
4. Click the options icon next to Upload artifact, and select Upload multiple artifacts.
5. Drag and drop or browse to the .zip download file that you exported earlier.
6. Click Upload and wait for the data to be imported.

Procedure

1. Add an artifact to Apicurio Registry using the /groups/{group}/artifacts operation. The following example curl command adds a simple schema artifact for a share price application:

   $ curl -X POST -H "Content-Type: application/json; artifactType=AVRO" \
     -H "X-Registry-ArtifactId: share-price" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data '{"type":"record","name":"price","namespace":"com.example", \
      "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' \
     MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts

   • This example adds an Apache Avro schema artifact with an artifact ID of share-price. If you do not specify a unique artifact ID, Apicurio Registry generates one automatically as a UUID.
   • MY-REGISTRY-URL is the host name on which Apicurio Registry is deployed. For example: my-cluster-service-registry-myproject.example.com.
   • This example specifies a group ID of my-group in the API path. If you do not specify a unique group ID, you must specify ../groups/default in the API path.

2. Verify that the response includes the expected JSON body to confirm that the artifact was added. For example:

   {"createdBy":"","createdOn":"2021-04-16T09:07:51+0000","modifiedBy":"",
   "modifiedOn":"2021-04-16T09:07:51+0000","id":"share-price","version":"1",
   "type":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2}

   • No version was specified when adding the artifact, so the default version 1 is created automatically.
   • This was the second artifact added to Apicurio Registry, so the global ID and content ID have a value of 2.

3. Retrieve the artifact content from Apicurio Registry using its artifact ID in the API path. In this example, the specified ID is share-price:

   $ curl -H "Authorization: Bearer $ACCESS_TOKEN" \
    MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts/share-price
    {"type":"record","name":"price","namespace":"com.example",
     "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}

Procedure

1. Add an artifact version in the registry using the /groups/{group}/artifacts operation. The following example curl command adds a simple artifact for a share price application:

   $ curl -X POST -H "Content-Type: application/json; artifactType=AVRO" \
     -H "X-Registry-ArtifactId: my-share-price" -H "X-Registry-Version: 1.1.1" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data '{"type":"record","name":" p","namespace":"com.example", \
      "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' \
      MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts

   • This example adds an Avro schema artifact with an artifact ID of my-share-price and version of 1.1.1. If you do not specify a version, Apicurio Registry automatically generates a default version of 1.
   • MY-REGISTRY-URL is the host name on which Apicurio Registry is deployed. For example: my-cluster-service-registry-myproject.example.com.
   • This example specifies a group ID of my-group in the API path. If you do not specify a unique group ID, you must specify ../groups/default in the API path.

2. Verify that the response includes the expected JSON body to confirm that the custom artifact version was added. For example:

   {"createdBy":"","createdOn":"2021-04-16T10:51:43+0000","modifiedBy":"",
   "modifiedOn":"2021-04-16T10:51:43+0000","id":"my-share-price","version":"1.1.1",
   "type":"AVRO","globalId":3,"state":"ENABLED","groupId":"my-group","contentId":3}

   • A custom version of 1.1.1 was specified when adding the artifact.
   • This was the third artifact added to the registry, so the global ID and content ID have a value of 3.

3. Retrieve the artifact content from the registry using its artifact ID and version in the API path. In this example, the specified ID is my-share-price and the version is 1.1.1:

   $ curl -H "Authorization: Bearer $ACCESS_TOKEN" \
   MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts/my-share-price/versions/1.1.1
   {"type":"record","name":"price","namespace":"com.example",
     "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}

Procedure

1. Add the ItemId schema artifact that you want to create the nested artifact reference to using the /groups/{group}/artifacts operation:

   $ curl -X POST MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts \
      -H "Content-Type: application/json; artifactType=AVRO" \
      -H "X-Registry-ArtifactId: ItemId" \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      --data '{"namespace": "com.example.common", "type": "record", "name": "ItemId", "fields":[{"name":"id", "type":"int"}]}'

   • This example adds an Avro schema artifact with an artifact ID of ItemId. If you do not specify a unique artifact ID, Apicurio Registry generates one automatically as a UUID.
   • MY-REGISTRY-URL is the host name on which Apicurio Registry is deployed. For example: my-cluster-service-registry-myproject.example.com.
   • This example specifies a group ID of my-group in the API path. If you do not specify a unique group ID, you must specify ../groups/default in the API path.

2. Verify that the response includes the expected JSON body to confirm that the artifact was added. For example:

   {"name":"ItemId","createdBy":"","createdOn":"2022-04-14T10:50:09+0000","modifiedBy":"","modifiedOn":"2022-04-14T10:50:09+0000","id":"ItemId","version":"1","type":"AVRO","globalId":1,"state":"ENABLED","groupId":"my-group","contentId":1,"references":[]}

3. Add the Item schema artifact that includes the artifact reference to the ItemId schema using the /groups/{group}/artifacts operation:

   $ curl -X POST MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts \
   -H 'Content-Type: application/create.extended+json' \
   -H "X-Registry-ArtifactId: Item" \
   -H 'X-Registry-ArtifactType: AVRO' \
   -H "Authorization: Bearer $ACCESS_TOKEN" \
   --data-raw '{
       "content": "{\r\n \"namespace\":\"com.example.common\",\r\n  \"name\":\"Item\",\r\n  \"type\":\"record\",\r\n  \"fields\":[\r\n   {\r\n  \"name\":\"itemId\",\r\n   \"type\":\"com.example.common.ItemId\"\r\n        }\r\n    ]\r\n}",
       "references": [
           {
               "groupId": "my-group",
               "artifactId": "ItemId",
               "name": "com.example.common.ItemId",
               "version": "1"
           }
       ]
   }'

   • For artifact references, you must specify the custom content type of application/create.extended+json, which extends the application/json content type.

4. Verify that the response includes the expected JSON body to confirm that the artifact was created with the reference. For example:

   {"name":"Item","createdBy":"","createdOn":"2022-04-14T11:52:15+0000","modifiedBy":"","modifiedOn":"2022-04-14T11:52:15+0000","id":"Item","version":"1","type":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2, "references":[{"artifactId":"ItemId","groupId":"my-group","name":"ItemId","version":"1"}] }

5. Retrieve the artifact reference from Apicurio Registry by specifying the global ID of the artifact that includes the reference. In this example, the specified global ID is 2:

   $ curl -H "Authorization: Bearer $ACCESS_TOKEN" MY-REGISTRY-URL/apis/registry/v2/ids/globalIds/2/references

6. Verify that the response includes the expected JSON body for this artifact reference. For example:

   [{"groupId":"my-group","artifactId":"ItemId","version":"1","name":"com.example.common.ItemId"}]

Procedure

1. Export the Apicurio Registry data from your existing source Apicurio Registry instance:

   $ curl MY-REGISTRY-URL/apis/registry/v2/admin/export \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --output my-registry-data.zip

   MY-REGISTRY-URL is the host name on which the source Apicurio Registry is deployed. For example: my-cluster-source-registry-myproject.example.com.

2. Import the registry data into your target Apicurio Registry instance:

   $ curl -X POST "MY-REGISTRY-URL/apis/registry/v2/admin/import" \
     -H "Content-Type: application/zip" -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data-binary @my-registry-data.zip

   MY-REGISTRY-URL is the host name on which the target Apicurio Registry is deployed. For example: my-cluster-target-registry-myproject.example.com.

Procedure

1. Update your Maven pom.xml file to use the apicurio-registry-maven-plugin to register an artifact. The following example shows registering Apache Avro and GraphQL schemas:

   <plugin>
     <groupId>io.apicurio</groupId>
     <artifactId>apicurio-registry-maven-plugin</artifactId>
     <version>${apicurio.version}</version>
     <executions>
         <execution>
           <phase>generate-sources</phase>
           <goals>
               <goal>register</goal>  1
           </goals>
           <configuration>
               <registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl> 2
               <authServerUrl>MY-AUTH-SERVER</authServerUrl>
               <clientId>MY-CLIENT-ID</clientId>
               <clientSecret>MY-CLIENT-SECRET</clientSecret> 3
               <clientScope>MY-CLIENT-SCOPE</clientScope>
               <artifacts>
                   <artifact>
                       <groupId>TestGroup</groupId> 4
                       <artifactId>FullNameRecord</artifactId>
                       <file>${project.basedir}/src/main/resources/schemas/record.avsc</file>
                       <ifExists>FAIL</ifExists>
                   </artifact>
                   <artifact>
                       <groupId>TestGroup</groupId>
                       <artifactId>ExampleAPI</artifactId> 5
                       <type>GRAPHQL</type>
                       <file>${project.basedir}/src/main/resources/apis/example.graphql</file>
                       <ifExists>RETURN_OR_UPDATE</ifExists>
                       <canonicalize>true</canonicalize>
                   </artifact>
               </artifacts>
           </configuration>
       </execution>
     </executions>
    </plugin>

   1

   Specify register as the execution goal to upload the schema artifact to Apicurio Registry.

   2

   Specify the Apicurio Registry URL with the ../apis/registry/v2 endpoint.

   3

   If authentication is required, you can specify your authentication server and client credentials.

   4

   Specify the Apicurio Registry artifact group ID. You can specify the default group if you do not want to use a unique group ID.

   5

   You can register multiple artifacts using the specified group ID, artifact ID, and location.

2. Build your Maven project, for example, by using the mvn package command.

Procedure

1. Update your Maven pom.xml file to use the apicurio-registry-maven-plugin to download an artifact. The following example shows downloading Apache Avro and GraphQL schemas.

   <plugin>
     <groupId>io.apicurio</groupId>
     <artifactId>apicurio-registry-maven-plugin</artifactId>
     <version>${apicurio.version}</version>
     <executions>
       <execution>
         <phase>generate-sources</phase>
         <goals>
           <goal>download</goal> 1
         </goals>
         <configuration>
             <registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl> 2
             <authServerUrl>MY-AUTH-SERVER</authServerUrl>
             <clientId>MY-CLIENT-ID</clientId>
             <clientSecret>MY-CLIENT-SECRET</clientSecret> 3
             <clientScope>MY-CLIENT-SCOPE</clientScope>
             <artifacts>
                 <artifact>
                     <groupId>TestGroup</groupId> 4
                     <artifactId>FullNameRecord</artifactId> 5
                     <file>${project.build.directory}/classes/record.avsc</file>
                     <overwrite>true</overwrite>
                 </artifact>
                 <artifact>
                     <groupId>TestGroup</groupId>
                     <artifactId>ExampleAPI</artifactId>
                     <version>1</version>
                     <file>${project.build.directory}/classes/example.graphql</file>
                     <overwrite>true</overwrite>
                 </artifact>
             </artifacts>
         </configuration>
       </execution>
     </executions>
   </plugin>

   1

   Specify download as the execution goal.

   2

   Specify the Apicurio Registry URL with the ../apis/registry/v2 endpoint.

   3

   If authentication is required, you can specify your authentication server and client credentials.

   4

   Specify the Apicurio Registry artifact group ID. You can specify the default group if you do not want to use a unique group.

   5

   You can download multiple artifacts to a specified directory using the artifact ID.

2. Build your Maven project, for example, by using the mvn package command.

Procedure

1. Update your Maven pom.xml file to use the apicurio-registry-maven-plugin to test an artifact. The following example shows testing an Apache Avro schema:

   <plugin>
     <groupId>io.apicurio</groupId>
     <artifactId>apicurio-registry-maven-plugin</artifactId>
     <version>${apicurio.version}</version>
     <executions>
         <execution>
           <phase>generate-sources</phase>
           <goals>
               <goal>test-update</goal>  1
           </goals>
           <configuration>
               <registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl> 2
               <authServerUrl>MY-AUTH-SERVER</authServerUrl>
               <clientId>MY-CLIENT-ID</clientId>
               <clientSecret>MY-CLIENT-SECRET</clientSecret> 3
               <clientScope>MY-CLIENT-SCOPE</clientScope>
               <artifacts>
                   <artifact>
                       <groupId>TestGroup</groupId> 4
                       <artifactId>FullNameRecord</artifactId>
                       <file>${project.basedir}/src/main/resources/schemas/record.avsc</file> 5
                   </artifact>
               </artifacts>
           </configuration>
       </execution>
     </executions>
    </plugin>

   1

   Specify test-update as the execution goal to test the schema artifact.

   2

   Specify the Apicurio Registry URL with the ../apis/registry/v2 endpoint.

   3

   If authentication is required, you can specify your authentication server and client credentials.

   4

   Specify the Apicurio Registry artifact group ID. You can specify the default group if you do not want to use a unique group.

   5

   You can test multiple artifacts from a specified directory using the artifact ID.

2. Build your Maven project, for example, by using the mvn package command.

Procedure

1. Update your Maven pom.xml file to use the apicurio-registry-maven-plugin to register the TradeKey schema, which includes a nested reference to the Exchange schema as follows:

   <plugin>
       <groupId>io.apicurio</groupId>
       <artifactId>apicurio-registry-maven-plugin</artifactId>
       <version>${apicurio-registry.version}</version>
       <executions>
           <execution>
               <phase>generate-sources</phase>
               <goals>
                   <goal>register</goal> 1
               </goals>
               <configuration>
                   <registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl> 2
                   <authServerUrl>MY-AUTH-SERVER</authServerUrl>
                   <clientId>MY-CLIENT-ID</clientId>
                   <clientSecret>MY-CLIENT-SECRET</clientSecret> 3
                   <clientScope>MY-CLIENT-SCOPE</clientScope>
                   <artifacts>
                       <artifact>
                           <groupId>test-group</groupId> 4
                           <artifactId>TradeKey</artifactId>
                           <version>2.0</version>
                           <type>AVRO</type>
                           <file>
                               ${project.basedir}/src/main/resources/schemas/TradeKey.avsc
                           </file>
                           <ifExists>RETURN_OR_UPDATE</ifExists>
                           <canonicalize>true</canonicalize>
                           <references>
                               <reference> 5
                                   <name>com.kubetrade.schema.common.Exchange</name>
                                   <groupId>test-group</groupId>
                                   <artifactId>Exchange</artifactId>
                                   <version>2.0</version>
                                   <type>AVRO</type>
                                   <file>
                                       ${project.basedir}/src/main/resources/schemas/Exchange.avsc
                                   </file>
                                   <ifExists>RETURN_OR_UPDATE</ifExists>
                                   <canonicalize>true</canonicalize>
                               </reference>
                           </references>
                       </artifact>
                   </artifacts>
               </configuration>
           </execution>
       </executions>
   </plugin>

   1

   Specify register as the execution goal to upload the schema artifacts to Apicurio Registry.

   2

   Specify the Apicurio Registry URL by using the ../apis/registry/v2 endpoint.

   3

   If authentication is required, you can specify your authentication server and client credentials.

   4

   Specify the Apicurio Registry artifact group ID. You can specify the default group if you do not want to use a unique group ID.

   5

   Specify the Apicurio Registry artifact reference using its group ID, artifact ID, version, type, and location. You can register multiple artifact references in this way.

2. Build your Maven project, for example, by using the mvn package command.

Procedure

1. Update your Maven pom.xml file to use the apicurio-registry-maven-plugin to register the TradeKey schema, which includes a nested reference to the Exchange schema as follows:

   <plugin>
       <groupId>io.apicurio</groupId>
       <artifactId>apicurio-registry-maven-plugin</artifactId>
       <version>${apicurio-registry.version}</version>
       <executions>
           <execution>
               <phase>generate-sources</phase>
               <goals>
                   <goal>register</goal> 1
               </goals>
               <configuration>
                   <registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl> 2
                   <authServerUrl>MY-AUTH-SERVER</authServerUrl>
                   <clientId>MY-CLIENT-ID</clientId>
                   <clientSecret>MY-CLIENT-SECRET</clientSecret> 3
                   <clientScope>MY-CLIENT-SCOPE</clientScope>
                   <artifacts>
                       <artifact>
                           <groupId>test-group</groupId> 4
                           <artifactId>TradeKey</artifactId>
                           <version>2.0</version>
                           <type>AVRO</type>
                           <file>
                               ${project.basedir}/src/main/resources/schemas/TradeKey.avsc 5
                           </file>
                           <ifExists>RETURN_OR_UPDATE</ifExists>
                           <canonicalize>true</canonicalize>
                           <autoRefs>true</autoRefs> 6
                       </artifact>
                   </artifacts>
               </configuration>
           </execution>
       </executions>
   </plugin>

   1

   Specify register as the execution goal to upload the schema artifacts to Apicurio Registry.

   2

   Specify the Apicurio Registry URL by using the ../apis/registry/v2 endpoint.

   3

   If authentication is required, you can specify your authentication server and client credentials.

   4

   Specify the parent artifact group ID that contains the references. You can specify the default group if you do not want to use a unique group ID.

   5

   Specify the location of the parent artifact file. All referenced artifacts must also be located in the same directory.

   6

   Set the <autoRefs> option to true to automatically detect and register all references to artifacts in the same directory. You can register multiple artifact references in this way.

2. Build your Maven project, for example, by using the mvn package command.

Procedure

1. Add the following dependency to your Maven project:

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

2. Create the Apicurio Registry client as follows:

   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/v2"; 1
          RegistryClient client = RegistryClientFactory.create(registryUrl); 2
       }
   }

   1

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

   2

   For more options when creating a Apicurio Registry client, see the Java client configuration in the next section.

Procedure

1. Configure the client with the URL of Apicurio Registry. For example:

   String registryUrl = "https://registry.example.com/apis/registry/v2";
   Properties props = new Properties();
   props.putIfAbsent(SerdeConfig.REGISTRY_URL, registryUrl);

2. Configure the client with the Apicurio Registry deserializer. For example:

   // Configure Kafka settings
   props.putIfAbsent(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, SERVERS);
   props.putIfAbsent(ConsumerConfig.GROUP_ID_CONFIG, "Consumer-" + TOPIC_NAME);
   props.putIfAbsent(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, "true");
   props.putIfAbsent(ConsumerConfig.AUTO_COMMIT_INTERVAL_MS_CONFIG, "1000");
   props.putIfAbsent(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");
   // Configure deserializer settings
   props.putIfAbsent(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG,
       AvroKafkaDeserializer.class.getName()); 1
   props.putIfAbsent(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG,
       AvroKafkaDeserializer.class.getName()); 2

   1

   The deserializer provided by Apicurio Registry.

   2

   The deserialization is in Apache Avro JSON format.

Procedure

1. Configure the client with the URL of Apicurio Registry. For example:

   String registryUrl = "https://registry.example.com/apis/registry/v2";
   Properties props = new Properties();
   props.putIfAbsent(SerdeConfig.REGISTRY_URL, registryUrl);

2. Configure the client with the serializer, and the strategy to look up the schema in Apicurio Registry. For example:

   props.put(CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG, "my-cluster-kafka-bootstrap:9092");
   props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, AvroKafkaSerializer.class.getName()); 1
   props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, AvroKafkaSerializer.class.getName()); 2
   props.put(SerdeConfig.FIND_LATEST_ARTIFACT, Boolean.TRUE); 3

   1

   The serializer for the message key provided by Apicurio Registry.

   2

   The serializer for the message value provided by Apicurio Registry.

   3

   The lookup strategy to find the global ID for the schema.

Procedure

1. Create and configure a Java client with the Apicurio Registry URL:

   String registryUrl = "https://registry.example.com/apis/registry/v2";
   
   RegistryService client = RegistryClient.cached(registryUrl);

2. Configure the serializer and deserializer:

   Serializer<LogInput> serializer = new AvroKafkaSerializer<LogInput>(); 1
   
   Deserializer<LogInput> deserializer = new AvroKafkaDeserializer <LogInput>(); 2
   
   Serde<LogInput> logSerde = Serdes.serdeFrom(
       serializer,
       deserializer
   );
   
   Map<String, Object> config = new HashMap<>();
   config.put(SerdeConfig.REGISTRY_URL, registryUrl);
   config.put(AvroKafkaSerdeConfig.USE_SPECIFIC_AVRO_READER, true);
   logSerde.configure(config, false); 3

   1

   The Avro serializer provided by Apicurio Registry.

   2

   The Avro deserializer provided by Apicurio Registry.

   3

   Configures the Apicurio Registry URL and the Avro reader for deserialization in Avro format.

3. Create the Kafka Streams client:

   KStream<String, LogInput> input = builder.stream(
       INPUT_TOPIC,
       Consumed.with(Serdes.String(), logSerde)
   );

1. The required URL of Apicurio Registry.
2. Extends ID handling to support other ID formats and make them compatible with Apicurio Registry SerDes services. For example, changing the default ID format from Long to Integer supports the Confluent ID format.
3. Simplifies the handling of Confluent IDs. If set to true, an Integer is used for the global ID lookup. The setting should not be used with the ID_HANDLER option.

1. The required serializer to use with the Apicurio Registry Kafka converter.
2. The required deserializer to use with the Apicurio Registry Kafka converter.