Managing Apicurio Registry content using the REST API
Client applications can use Apicurio Registry REST API operations to manage schema and API artifacts in Apicurio 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 Apicurio 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:
-
Managing schema and API artifacts using Apicurio Registry REST API commands
-
Managing schema and API artifact versions using Apicurio Registry REST API commands
-
Managing schema and API artifact references using Apicurio Registry REST API commands
-
Exporting and importing registry data using Apicurio Registry REST API commands
Managing schema and API artifacts using Apicurio 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 Apicurio Registry.
-
Apicurio Registry is installed and running in your environment.
-
Add an artifact to Apicurio Registry using the
/groups/{group}/artifacts
operation. The following examplecurl
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: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.
-
-
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
.
-
-
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"}]}
-
For more details, see the Apicurio Registry REST API documentation.
Managing schema and API artifact versions using Apicurio Registry REST API commands
If you do not specify an artifact version when adding schema and API artifacts using the Core Registry API v2, Apicurio Registry generates a version automatically. The default version when creating a new artifact is 1
.
Apicurio 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 Apicurio Registry. You can specify custom versions to add or update artifacts, or to add artifact versions.
-
Apicurio Registry is installed and running in your environment.
-
Add an artifact version in the registry using the
/groups/{group}/artifacts
operation. The following examplecurl
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 of1.1.1
. If you do not specify a version, Apicurio Registry automatically generates a default version of1
. -
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.
-
-
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 is1.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"}]}
-
For more details, see the Apicurio Registry REST API documentation.
Managing schema and API artifact references using Apicurio Registry REST API commands
Some Apicurio 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 Apicurio Registry.
This example first creates a schema artifact named ItemId
:
{
"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.
{
"namespace":"com.example.common",
"name":"Item",
"type":"record",
"fields":[
{
"name":"itemId",
"type":"com.example.common.ItemId"
},
]
}
-
Apicurio Registry is installed and running in your environment.
-
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: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.
-
-
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 theItemId
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 theapplication/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 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
-
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"}]
There are some cases where returning artifact content with referenced content inline might be helpful. For these cases, the Core Registry API v2 supports the dereference
query parameter in certain operations.
This support is currently implemented only for Avro, Protobuf, OpenAPI, AsyncAPI, and JSON Schema artifacts when the dereference
parameter is specified in the API operation. This parameter is not supported for any other artifact types.
For Protobuf artifacts, dereferencing content is supported only when all the schemas belong to the same package. |
Circular dependencies are allowed by some artifact types (e.g. JSON Schema) but are not supported by Apicurio Registry. |
-
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 Configuring Kafka serializers/deserializers in Java clients.
Exporting and importing registry data using Apicurio Registry REST API commands
As an administrator, you can use the Core Registry API v2 to export data from one Apicurio Registry instance and import into another Apicurio 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 Apicurio Registry instance to another. All of the artifact data contained in the Apicurio Registry instance is exported in the .zip
file.
You can import only Apicurio Registry data that has been exported from another Apicurio Registry instance. |
-
Apicurio Registry is installed and running in your environment.
-
Apicurio 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.
-
-
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:http://my-source-registry:8080
. -
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:http://my-target-registry:8080
.
-
For more details, see the
admin
endpoint in the Apicurio Registry REST API documentation. -
For details on export tools for migrating from Apicurio Registry version 1.x to 2.x, see Apicurio Registry export utility for 1.x versions.