Chapter 4. Managing Service Registry content using the REST API Client applications can use Service Registry REST API operations to manage schema and API artifacts in Service Registry, for example, in a CI/CD pipeline deployed in production. The Core Registry API v2 provides operations for artifacts, versions, metadata, and rules stored in Service Registry. For detailed information, see the Apicurio Registry REST API documentation . This chapter shows examples of how to use the Core Registry API v2 to perform the following tasks: Section 4.1, "Managing schema and API artifacts using Service Registry REST API commands" Section 4.2, "Managing schema and API artifact versions using Service Registry REST API commands" Section 4.3, "Managing schema and API artifact references using Service Registry REST API commands" Section 4.4, "Exporting and importing registry data using Service Registry REST API commands" Prerequisites Chapter 1, Introduction to Service Registry Additional resources Apicurio Registry REST API documentation 4.1. Managing schema and API artifacts using Service Registry REST API commands This section shows a simple curl-based example of using the Core Registry API v2 to add and retrieve a simple schema artifact in Service Registry. Prerequisites Service Registry is installed and running in your environment. Procedure Add an artifact to Service Registry using the /groups/{group}/artifacts operation. The following example curl command adds a simple schema artifact for a share price application: USD curl -X POST -H "Content-Type: application/json; artifactType=AVRO" \ -H "X-Registry-ArtifactId: share-price" \ -H "Authorization: Bearer USDACCESS_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, Service Registry generates one automatically as a UUID. MY-REGISTRY-URL is the host name on which Service 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. 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 Service Registry, so the global ID and content ID have a value of 2 . Retrieve the artifact content from Service Registry using its artifact ID in the API path. In this example, the specified ID is share-price : USD curl -H "Authorization: Bearer USDACCESS_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"}]} Additional resources For more details, see the Apicurio Registry REST API documentation . 4.2. Managing schema and API artifact versions using Service Registry REST API commands If you do not specify an artifact version when adding schema and API artifacts using the Core Registry API v2, Service Registry generates a version automatically. The default version when creating a new artifact is 1 . Service Registry also supports custom versioning where you can specify a version using the X-Registry-Version HTTP request header as a string. Specifying a custom version value overrides the default version normally assigned when creating or updating an artifact. You can then use this version value when executing REST API operations that require a version. This section shows a simple curl-based example of using the Core Registry API v2 to add and retrieve a custom Apache Avro schema version in Service Registry. You can specify custom versions to add or update artifacts, or to add artifact versions. Prerequisites Service Registry is installed and running in your environment. Procedure 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: USD 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 USDACCESS_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, Service Registry automatically generates a default version of 1 . MY-REGISTRY-URL is the host name on which Service 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. 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 . 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 : USD curl -H "Authorization: Bearer USDACCESS_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"}]} Additional resources For more details, see the Apicurio Registry REST API documentation . 4.3. Managing schema and API artifact references using Service Registry REST API commands Some Service Registry artifact types can include artifact references from one artifact file to another. You can create efficiencies by defining reusable schema or API artifacts, and then referencing them from multiple locations in artifact references. The following artifact types support artifact references: Apache Avro Google Protobuf JSON Schema OpenAPI AsyncAPI This section shows a simple curl-based example of using the Core Registry API v2 to add and retrieve an artifact reference to a simple Avro schema artifact in Service Registry. This example first creates a schema artifact named ItemId : ItemId schema { "namespace":"com.example.common", "name":"ItemId", "type":"record", "fields":[ { "name":"id", "type":"int" } ] } This example then creates a schema artifact named Item , which includes a reference to the nested ItemId artifact. Item schema with nested ItemId schema { "namespace":"com.example.common", "name":"Item", "type":"record", "fields":[ { "name":"itemId", "type":"com.example.common.ItemId" }, ] } Prerequisites Service Registry is installed and running in your environment. Procedure Add the ItemId schema artifact that you want to create the nested artifact reference to using the /groups/{group}/artifacts operation: USD 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 USDACCESS_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, Service Registry generates one automatically as a UUID. MY-REGISTRY-URL is the host name on which Service 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. 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":[]} Add the Item schema artifact that includes the artifact reference to the ItemId schema using the /groups/{group}/artifacts operation: USD 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 USDACCESS_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. 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"}] } Retrieve the artifact reference from Service Registry by specifying the global ID of the artifact that includes the reference. In this example, the specified global ID is 2 : USD curl -H "Authorization: Bearer USDACCESS_TOKEN" MY-REGISTRY-URL/apis/registry/v2/ids/globalIds/2/references 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"}] Additional resources For more details, see the Apicurio Registry REST API documentation . For more examples of artifact references, see the section on configuring each artifact type in Chapter 8, Configuring Kafka serializers/deserializers in Java clients . 4.4. Exporting and importing registry data using Service Registry REST API commands As an administrator, you can use the Core Registry API v2 to export data from one Service Registry instance and import into another Service Registry instance, so you can migrate data between different instances. This section shows a simple curl-based example of using the Core Registry API v2 to export and import existing data in .zip format from one Service Registry instance to another. All of the artifact data contained in the Service Registry instance is exported in the .zip file. Note You can import only Service Registry data that has been exported from another Service Registry instance. Prerequisites Service Registry is installed and running in your environment. Service Registry instances have been created: The source instance that you want to export data from contains at least one schema or API artifact. The target instance that you want to import data into is empty to preserve unique IDs. Procedure Export the Service Registry data from your existing source Service Registry instance: USD curl MY-REGISTRY-URL/apis/registry/v2/admin/export \ -H "Authorization: Bearer USDACCESS_TOKEN" \ --output my-registry-data.zip MY-REGISTRY-URL is the host name on which the source Service Registry is deployed. For example: my-cluster-source-registry-myproject.example.com . Import the registry data into your target Service Registry instance: USD curl -X POST "MY-REGISTRY-URL/apis/registry/v2/admin/import" \ -H "Content-Type: application/zip" -H "Authorization: Bearer USDACCESS_TOKEN" \ --data-binary @my-registry-data.zip MY-REGISTRY-URL is the host name on which the target Service Registry is deployed. For example: my-cluster-target-registry-myproject.example.com . Additional resources For more details, see the admin endpoint in the Apicurio Registry REST API documentation . For details on export tools for migrating from Service Registry version 1.x to 2.x, see Apicurio Registry export utility for 1.x versions .

Commands:
curl -X POST -H "Content-Type: application/json; artifactType=AVRO" -H "X-Registry-ArtifactId: share-price" -H "Authorization: Bearer USDACCESS_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
createdOn: 2021-04-16T09:07:51+0000
modifiedOn: 2021-04-16T09:07:51+0000
id: share-price
version: 1
type: AVRO
globalId: 2
state: ENABLED
groupId: my-group
contentId: 2
curl -H "Authorization: Bearer USDACCESS_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"}]}
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 USDACCESS_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
createdOn: 2021-04-16T10:51:43+0000
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
curl -H "Authorization: Bearer USDACCESS_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"}]}
{ "namespace":"com.example.common", "name":"ItemId", "type":"record", "fields":[ { "name":"id", "type":"int" } ] }
{ "namespace":"com.example.common", "name":"Item", "type":"record", "fields":[ { "name":"itemId", "type":"com.example.common.ItemId" }, ] }
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 USDACCESS_TOKEN" --data '{"namespace": "com.example.common", "type": "record", "name": "ItemId", "fields":[{"name":"id", "type":"int"}]}'
{"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":[]}
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 USDACCESS_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" } ] }'
{"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"}] }
curl -H "Authorization: Bearer USDACCESS_TOKEN" MY-REGISTRY-URL/apis/registry/v2/ids/globalIds/2/references
groupId: my-group
artifactId: ItemId
version: 1
name: com.example.common.ItemId
curl MY-REGISTRY-URL/apis/registry/v2/admin/export -H "Authorization: Bearer USDACCESS_TOKEN" --output my-registry-data.zip
curl -X POST "MY-REGISTRY-URL/apis/registry/v2/admin/import" -H "Content-Type: application/zip" -H "Authorization: Bearer USDACCESS_TOKEN" --data-binary @my-registry-data.zip