Apicurio Registry User Guide

Procedure

1. In the Red Hat build of Keycloak Admin Console, create a Red Hat build of Keycloak realm for Apicurio Registry. By default, Apicurio Registry expects a realm name of registry. For details on creating realms, see the the Red Hat build of Keycloak user documentation.

2. Create a Red Hat build of Keycloak client for the Apicurio Registry API. By default, Apicurio Registry expects the following settings:

   • Client ID: registry-api
   • Client Protocol: openid-connect

   • Access Type: bearer-only

     You can use the defaults for the other client settings.

     Note

     If you are using Red Hat build of Keycloak service accounts, the client Access Type must be confidential instead of bearer-only.

3. Create a Red Hat build of Keycloak client for the Apicurio Registry web console. By default, Apicurio Registry expects the following settings:

   • Client ID: apicurio-registry
   • Client Protocol: openid-connect
   • Access Type: public
   • Valid Redirect URLs: http://my-registry-url:8080/*

   • Web Origins: +

     You can use the defaults for the other client settings.

4. In your Apicurio Registry deployment on OpenShift, set the following Apicurio Registry environment variables to configure authentication using Red Hat build of Keycloak:

   Expand

   Table 3.1. Configuration for Apicurio Registry authentication with Red Hat build of Keycloak

   Environment variable	Description	Type	Default
   QUARKUS_OIDC_TENANT_ENABLED	Enables authentication for Apicurio Registry. When set to true, the environment variables that follow are required for authentication using Red Hat build of Keycloak.	String	false
   QUARKUS_OIDC_AUTH_SERVER_URL	The URL of the Red Hat build of Keycloak authentication server. For example, http://localhost:8080.	String	-
   QUARKUS_OIDC_CLIENT_ID	The client ID for the Apicurio Registry REST API.	String	registry-api
   APICURIO_UI_AUTH_OIDC_CLIENT-ID	The client ID for the Apicurio Registry web console.	String	apicurio-registry

   Show more
   Tip

   For an example of setting environment variables on OpenShift, see Section 4.1.1, “Configuring Apicurio Registry health checks on OpenShift”.

5. Set the following option to true to enable Apicurio Registry user roles in Red Hat build of Keycloak:

   Expand

   Table 3.2. Configuration for Apicurio Registry role-based authorization

   Environment variable	Java system property	Type	Default value
   APICURIO_AUTH_ROLE-BASED-AUTHORIZATION	apicurio.auth.role-based-authorization	Boolean	false

   Show more

6. When Apicurio Registry user roles are enabled, you must assign Apicurio Registry users to at least one of the following default user roles in your Red Hat build of Keycloak realm:

   Expand

   Table 3.3. Default user roles for registry authentication and authorization

   Role	Read artifacts	Write artifacts	Global rules	Summary
   sr-admin	Yes	Yes	Yes	Full access to all create, read, update, and delete operations.
   sr-developer	Yes	Yes	No	Access to create, read, update, and delete operations, except configuring global rules. This role can configure artifact-specific rules.
   sr-readonly	Yes	No	No	Access to read and search operations only. This role cannot configure any rules.

   Show more

7. Set the following to true to enable owner-only authorization for updates to schema and API artifacts in Apicurio Registry:

   Expand

   Table 3.4. Configuration for owner-only authorization

   Environment variable	Java system property	Type	Default value
   APICURIO_AUTH_OWNER-ONLY-AUTHORIZATION_LIMIT-GROUP-ACCESS	apicurio.auth.owner-only-authorization.limit-group-access	Boolean	false

   Show more

Procedure

1. Log in to the Azure AD portal using your email address or GitHub account.

2. In the navigation menu, select Manage > App registrations > New registration, and complete the following settings:

   • Name: Enter your application name. For example: apicurio-registry-example
   • Supported account types: Click Accounts in any organizational directory.

   • Redirect URI: Select Single-page application from the list, and enter your Apicurio Registry web console application host. For example: https://test-registry.com/ui/

     Important

     You must register your Apicurio Registry application host as a Redirect URI. When logging in, users are redirected from Apicurio Registry to Azure AD for authentication, and you want to send them back to your application afterwards. Azure AD does not allow any redirect URLs that are not registered.

3. Click Register. You can view your app registration details by selecting Manage > App registrations > apicurio-registry-example.

4. Select Manage > Authentication and ensure that the application is configured with your redirect URLs and tokens as follows:

   • Redirect URIs: For example: https://test-registry.com/ui/
   • Implicit grant and hybrid flows: Click ID tokens (used for implicit and hybrid flows)
5. Select Azure AD > Admin > App registrations > Your app > Application (client) ID. For example: 123456a7-b8c9-012d-e3f4-5fg67h8i901
6. Select Azure AD > Admin > App registrations > Your app > Directory (tenant) ID. For example: https://login.microsoftonline.com/1a2bc34d-567e-89f1-g0hi-1j2kl3m4no56/v2.0

7. In Apicurio Registry, configure the following environment variables with your Azure AD settings:

   Expand

   Table 3.5. Configuration for Azure AD settings in Apicurio Registry

   Environment variable	Description	Setting
   QUARKUS_OIDC_CLIENT-ID	The client application ID for the Apicurio Registry REST API	Your Azure AD Application (client) ID obtained in step 5. For example: 123456a7-b8c9-012d-e3f4-5fg67h8i901
   APICURIO_UI_AUTH_OIDC_CLIENT-ID	The client application ID for the Apicurio Registry web console.	Your Azure AD Application (client) ID obtained in step 5. For example: 123456a7-b8c9-012d-e3f4-5fg67h8i901
   QUARKUS_OIDC_AUTH-SERVER-URL	The URL for authentication in Azure AD.	Your Azure AD Application (tenant) ID obtained in step 6. For example: https://login.microsoftonline.com/1a2bc34d-567e-89f1-g0hi-1j2kl3m4no56/v2.0.

   Show more

8. In Apicurio Registry, configure the following environment variables for Apicurio Registry-specific settings:

   Expand

   Table 3.6. Configuration for Apicurio Registry-specific settings

   Environment variable	Description	Setting
   QUARKUS_OIDC_TENANT-ENABLED	Enables authentication for Apicurio Registry.	true
   QUARKUS_HTTP_CORS_ORIGINS	The host for your Apicurio Registry deployment for cross-origin resource sharing (CORS).	For example: https://test-registry.com
   APICURIO_UI_AUTH_OIDC_REDIRECT-URI	The host for your Apicurio Registry web console.	For example: https://test-registry.com/ui
   APICURIO_AUTH_ROLE-BASED-AUTHORIZATION	Enables role-based authorization in Apicurio Registry.	true
   QUARKUS_OIDC_ROLES_ROLE-CLAIM-PATH	The name of the claim in which Azure AD stores roles.	roles

   Show more
   Note

   When you enable roles in Apicurio Registry, you must also create the same roles in Azure AD as application roles. The default roles expected by Apicurio Registry are sr-admin, sr-developer, and sr-readonly.

9. In Apicurio Registry UI, configure the following environment variables:

Procedure

1. On the Explore 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 5.1. Artifacts in Apicurio Registry web console

   

   View larger image

   

2. Click an artifact to view the following details:

   • Overview: Displays artifact metadata such as artifact ID, name, description, labels, and so on. Also displays rules for validity and compatibility that you can configure for artifact content.
   • Versions: Displays a list of all artifact versions. This will be empty unless you chose to upload a first version when you created the artifact.

   • Branches: Displays a list of branches for the artifact. This will display at least the latest branch, but might display other generated branches depending on your configuration.

     Figure 5.2. Artifact details in Apicurio Registry web console

     

     View larger image

     

3. Click the Versions tab to view a list of all artifact versions. Then click one of the versions in the list, or choose View Version from the Action menu for a version in the list. You will then see the following artifact version details:

   • Overview: Displays artifact version metadata such as version name, description, global ID, content ID, labels, and so on. Also displays any comments created for the artifact version.
   • Documentation (OpenAPI and AsyncAPI only): Displays automatically-generated REST API documentation.
   • Content: Displays a read-only view of the full artifact version 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 version. You can also click View artifacts that reference this artifact version.

     Figure 5.3. Artifact version details in Apicurio Registry web console

     

     View larger image

     
4. To save the artifact contents to a local file, for example, my-openapi.json or my-protobuf-schema.proto, and click Download.

Procedure

1. On the Explore tab, click Create artifact, and complete the Create artifact wizard:

   Note

   You can create a placeholder artifact without content, but you must specify the artifact type, as Apicurio Registry cannot automatically detect the content type. Creating a placeholder allows you create rules first and add content later.

   1. Specify the Artifact Coordinates and click Next:

      • Group ID & Artifact 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 or artifact ID.
      • Type: Use the default Auto-Detect setting to automatically detect the artifact type (not allowed if creating an empty artifact), 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.

   2. Specify the Artifact Metadata and click Next:

      • Name: Enter an optional friendly name for the new artifact.
      • Description: Enter an optional description for the new artifact.
      • Labels: Optionally add one or more label (name/value pair) for the new artifact.

   3. Specify the Version Content and click Next:

      • Version Number: Optionally add a version string if creating a first version.

      • Content: Specify the content 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.

   4. Specify the Version Metadata:

      • Name: Enter an optional friendly name for the first artifact version.
      • Description: Enter an optional description for the first artifact version.
      • Labels: Optionally add one or more label (name/value pair) for the first artifact version.

2. Click Create and view the artifact details:

   • Overview: Displays artifact metadata such as artifact ID, name, description, labels, and so on. Also displays rules for validity and compatibility that you can configure for artifact content.
   • Versions: Displays a list of all artifact versions. This will be empty unless you chose to upload a first version when you created the artifact.

   • Branches: Displays a list of branches for the artifact. This will display at least the latest branch, but might display other generated branches depending on your configuration.

     The following example shows an example Apache Avro artifact:

     Figure 5.4. Artifact details in Apicurio Registry web console

     

     View larger image

     

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

   You can also add zero or more labels (name + value) for categorizing and searching purposes. To add labels, perform the following steps:

   1. Click Add label.
   2. Enter the key name and the value (optional).
   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, switch to the Versions tab and then click Create version in the toolbar. From there, provide the following information:

   1. Version Number: Optionally add a version string for the new version.

   2. Content: Specify the content using either of the following options:

      1. 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.
      2. From URL: Enter a valid and accessible URL, and click Fetch. For example: https://petstore3.swagger.io/api/v3/openapi.json.
   3. Now you can click the Create button to create the new version.

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 (group-specific rules)

1. On the Explore tab, browse the list of groups in Apicurio Registry by selecting Groups from the "Search for" menu.
2. Click a group to view its details and content rules.

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

   Figure 5.5. Group-specific rules in Apicurio Registry web console

   

   View larger image

   

Procedure (artifact-specific rules)

1. On the Explore tab, browse the list of artifacts in Apicurio Registry by selecting Artifacts from the "Search for" menu.
2. Click an artifact from the list to view its 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 5.6. Artifact content rules in Apicurio Registry web console

   

   View larger image

   

Procedure (global rules)

1. To access global rules, click the Global rules tab.

2. Click Enable to configure global validity, compatibility, or integrity rules for all artifact content, and select the appropriate rule configuration from the list.

   Figure 5.7. Artifact content rules in Apicurio Registry web console

   

   View larger image

   

Procedure

1. On the Explore 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 Overview 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 Apicurio Registry:

   Expand

   Table 5.1. Authentication settings

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

   Show more
   Expand

   Table 5.2. Authorization settings

   Setting	Description
   Anonymous read access	Displayed only when authentication is already enabled. 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 Apicurio Registry 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 also enabled. 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.

   Show more
   Expand

   Table 5.3. Compatibility settings

   Setting	Description
   Canonical hash mode (compatibility API)	When selected, the Schema Registry compatibility API uses the canonical hash instead of the regular hash of the content.
   Legacy ID mode (compatibility API)	When selected, the Confluent Schema Registry compatibility API uses globalId instead of contentId as an artifact identifier.
   Maximum number of Subjects returned (compatibility API)	Determines the maximum number of Subjects that will be returned by the Confluent Schema Registry compatibility API (for the /subjects endpoint).

   Show more
   Expand

   Table 5.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 Apicurio Registry. Defaults to 30 seconds.

   Show more
   Expand

   Table 5.5. Semantic versioning settings

   Setting	Description
   Automatically create semver branches	When enabled, automatically create or update branches for major ('A.x') and minor ('A.B.x') artifact versions.
   Ensure all version numbers are 'semver' compatible	When enabled, validate that all artifact versions conform to Semantic Versioning 2 format (https://semver.org).

   Show more
   Expand

   Table 5.6. Additional properties

   Setting	Description
   Delete artifact	When selected, users are permitted to delete artifacts in Apicurio Registry by using the Core Registry API. Not selected by default.
   Delete artifact version	When selected, users are permitted to delete artifact versions in Apicurio Registry by using the Core Registry API. Not selected by default.
   Delete group	When selected, users are permitted to delete groups in Apicurio Registry by using the Core Registry API. Not selected by default.
   Storage read-only mode	When selected, Registry will return an error for operations that write to the storage (this property excepted). Not enabled by default.

   Show more

Procedure

1. In the web console for the source Apicurio Registry instance, view the Explore tab.
2. Click the additional actions icon (three vertical dots) next to Create artifact in the toolbar, and select Export all (as .ZIP) to export the data for this Apicurio Registry instance to a .zip download file.
3. In the web console for the target Apicurio Registry instance, view the Explore tab.
4. Click the additional actions icon (three vertical dots) next to Create artifact in the toolbar, and select Import from .ZIP.
5. Drag and drop or browse to the .zip download file that you exported earlier.
6. Click Import and wait for the data to be imported.

Procedure

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

   $ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data-raw '{
       "artifactId": "share-price",
       "artifactType": "AVRO",
       "firstVersion": {
           "content": {
               "content": "{\"type\":\"record\",\"name\":\" p\",\"namespace\":\"com.example\", \"fields\":[{\"name\":\"symbol\",\"type\":\"string\"},{\"name\":\"price\",\"type\":\"string\"}]}",
               "contentType": "application/json"
           }
       }
   }'

   Copy to Clipboard Toggle word wrap
   • 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: http://localhost:8080.
   • 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:

   {"artifact":{"owner":"","createdOn":"2024-09-26T17:24:21Z","modifiedBy":"","modifiedOn":"2024-09-26T17:24:21Z","artifactType":"AVRO","groupId":"my-group","artifactId":"share-price"},"version":{"version":"1","owner":"","createdOn":"2024-09-26T17:24:21Z","artifactType":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2,"artifactId":"share-price"}}

   Copy to Clipboard Toggle word wrap
   • 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 version 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/v3/groups/my-group/artifacts/share-price/versions/1/content
    {"type":"record","name":"price","namespace":"com.example",
     "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}

   Copy to Clipboard Toggle word wrap

Procedure

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

   $ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data-raw '{
       "artifactId": "my-share-price",
       "artifactType": "AVRO",
       "firstVersion": {
           "version": "1.1.1",
           "content": {
               "content": "{\"type\":\"record\",\"name\":\" p\",\"namespace\":\"com.example\", \"fields\":[{\"name\":\"symbol\",\"type\":\"string\"},{\"name\":\"price\",\"type\":\"string\"}]}",
               "contentType": "application/json"
           }
       }
   }'

   Copy to Clipboard Toggle word wrap
   • 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: http://localhost:8080.
   • 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:

   {"artifact":{"owner":"","createdOn":"2024-09-26T17:06:21Z","modifiedBy":"","modifiedOn":"2024-09-26T17:06:21Z","artifactType":"AVRO","groupId":"my-group","artifactId":"my-share-price"},"version":{"version":"1.1.1","owner":"","createdOn":"2024-09-26T17:06:21Z","artifactType":"AVRO","globalId":4,"state":"ENABLED","groupId":"my-group","contentId":4,"artifactId":"my-share-price"}}

   Copy to Clipboard Toggle word wrap
   • A custom version of 1.1.1 was specified when adding the artifact.
   • This was the fourth artifact added to the registry, so the global ID and content ID have a value of 4.

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/v3/groups/my-group/artifacts/my-share-price/versions/1.1.1/content
   {"type":"record","name":"price","namespace":"com.example",
     "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}

   Copy to Clipboard Toggle word wrap

Procedure

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

   $ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      --data '{"artifactId":"ItemId","artifactType":"AVRO","firstVersion":{"version":"1.0.0","content":{"content":"{\"namespace\":\"com.example.common\",\"name\":\"ItemId\",\"type\":\"record\",\"fields\":[{\"name\":\"id\",\"type\":\"int\"}]}","contentType":"application/json"}}}'

   Copy to Clipboard Toggle word wrap
   • 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: http://localhost:8080.
   • 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:

   {"artifact":{"owner":"","createdOn":"2024-09-26T16:27:38Z","modifiedBy":"","modifiedOn":"2024-09-26T16:27:38Z","artifactType":"AVRO","groupId":"my-group","artifactId":"ItemId"},"version":{"version":"1.0.0","owner":"","createdOn":"2024-09-26T16:27:38Z","artifactType":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2,"artifactId":"ItemId"}}

   Copy to Clipboard Toggle word wrap

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

   $ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \
   -H 'Content-Type: application/json' \
   -H "Authorization: Bearer $ACCESS_TOKEN" \
   --data-raw '{
   	"artifactId": "Item",
   	"artifactType": "AVRO",
   	"firstVersion": {
   		"version": "1.0.0",
   		"content": {
   			"content": "{\"namespace\":\"com.example.common\",\"name\":\"Item\",\"type\":\"record\",\"fields\":[{\"name\":\"itemId\",\"type\":\"com.example.common.ItemId\"}]}",
   			"contentType": "application/json",
   			"references": [
   				{
   					"name": "com.example.common.ItemId",
   					"groupId": "my-group",
   					"artifactId": "ItemId",
   					"version": "1.0.0"
   				}
   			]
   		}
   	}
   }'

   Copy to Clipboard Toggle word wrap

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

   {"artifact":{"owner":"","createdOn":"2024-09-26T16:28:45Z","modifiedBy":"","modifiedOn":"2024-09-26T16:28:45Z","artifactType":"AVRO","groupId":"my-group","artifactId":"Item"},"version":{"version":"1.0.0","owner":"","createdOn":"2024-09-26T16:28:45Z","artifactType":"AVRO","globalId":3,"state":"ENABLED","groupId":"my-group","contentId":3,"artifactId":"Item"}}

   Copy to Clipboard Toggle word wrap

5. Retrieve the artifact reference from Apicurio Registry by specifying the coordinates of the artifact that includes the reference:

   $ curl -H "Authorization: Bearer $ACCESS_TOKEN" MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts/Item/versions/1.0.0/references

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

1. Retrieve the dereferenced (inlined) schema content:

   $ curl -H "Authorization: Bearer $ACCESS_TOKEN" MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts/Item/versions/1.0.0/content?references=DEREFERENCE

   Copy to Clipboard Toggle word wrap

2. Verify that the response includes the expected JSON body for this artifact content with the references inlined. For example:

   {"type":"record","name":"Item","namespace":"com.example.common","fields":[{"name":"itemId","type":{"type":"record","name":"ItemId","fields":[{"name":"id","type":"int"}]}}]}

   Copy to Clipboard Toggle word wrap

Procedure

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

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

   Copy to Clipboard Toggle word wrap

   MY-REGISTRY-URL is the host name on which the source Apicurio Registry is deployed. For example: http://my-source-registry:8080.

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

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

   Copy to Clipboard Toggle word wrap

   MY-REGISTRY-URL is the host name on which the target Apicurio Registry is deployed. For example: http://my-target-registry:8080.

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/v3</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

   
                       <artifactType>GRAPHQL</artifactType>
                       <file>${project.basedir}/src/main/resources/apis/example.graphql</file>
                       <ifExists>FIND_OR_CREATE_VERSION</ifExists>
                       <canonicalize>true</canonicalize>
                   </artifact>
               </artifacts>
           </configuration>
       </execution>
     </executions>
    </plugin>

   Copy to Clipboard Toggle word wrap

   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/v3 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/v3</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>

   Copy to Clipboard Toggle word wrap

   1

   Specify download as the execution goal.

   2

   Specify the Apicurio Registry URL with the ../apis/registry/v3 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/v3</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>

   Copy to Clipboard Toggle word wrap

   1

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

   2

   Specify the Apicurio Registry URL with the ../apis/registry/v3 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/v3</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>
                           <artifactType>AVRO</artifactType>
                           <file>
                               ${project.basedir}/src/main/resources/schemas/TradeKey.avsc
                           </file>
                           <ifExists>FIND_OR_CREATE_VERSION</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>
                                   <artifactType>AVRO</artifactType>
                                   <file>
                                       ${project.basedir}/src/main/resources/schemas/Exchange.avsc
                                   </file>
                                   <ifExists>FIND_OR_CREATE_VERSION</ifExists>
                                   <canonicalize>true</canonicalize>
                               </reference>
                           </references>
                       </artifact>
                   </artifacts>
               </configuration>
           </execution>
       </executions>
   </plugin>

   Copy to Clipboard Toggle word wrap

   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/v3 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/v3</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>
                           <artifactType>AVRO</artifactType>
                           <file>
                               ${project.basedir}/src/main/resources/schemas/TradeKey.avsc 

   5

   
                           </file>
                           <ifExists>FIND_OR_CREATE_VERSION</ifExists>
                           <canonicalize>true</canonicalize>
                           <autoRefs>true</autoRefs> 

   6

   
                       </artifact>
                   </artifacts>
               </configuration>
           </execution>
       </executions>
   </plugin>

   Copy to Clipboard Toggle word wrap

   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/v3 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. Configure the client with the URL of Apicurio Registry. For example:

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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/v3";
   Properties props = new Properties();
   props.putIfAbsent(SerdeConfig.REGISTRY_URL, registryUrl);

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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/v3";
   
   RegistryService client = RegistryClient.cached(registryUrl);

   Copy to Clipboard Toggle word wrap

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(AvroSerdeConfig.USE_SPECIFIC_AVRO_READER, true);
   logSerde.configure(config, false); 

   3

   Copy to Clipboard Toggle word wrap

   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)
   );

   Copy to Clipboard Toggle word wrap

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, you may change it from the default ID format Integer that’s also compatible with Confluent’s ID format to Long.

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