Apicurio Studio

Managing Apicurio Registry content using the REST API

Client applications can use Registry REST API operations to manage schema and API artifacts in Apicurio Registry, for example, in a CI/CD pipeline deployed in production. The Registry REST API provides create, read, update, and delete operations for artifacts, versions, metadata, and rules stored in the registry. For detailed information, see the Apicurio Registry REST API documentation.

This chapter describes the Apicurio Registry core REST API and shows how to use it to manage schema and API artifacts stored in the registry:

Prerequisites
Additional resources

Managing schema and API artifacts using Apicurio Registry REST API commands

This section shows a simple curl-based example of using the Apicurio Registry core REST API to add and retrieve an Apache Avro schema artifact in Apicurio Registry.

Prerequisites

  • Apicurio Registry is installed and running in your environment

Procedure

  1. Add an artifact to 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: 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 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:

    {"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 the registry, so the global ID and content ID have a value of 2.

  3. Retrieve the artifact content from the 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"}]}
Additional resources

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 to Apicurio Registry using the v2 core REST API, Apicurio Registry generates one 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 registry v2 core REST API to add and retrieve a custom Apache Avro schema version in the registry. You can specify custom versions when using the REST API to add or update artifacts or to add artifact versions.

Prerequisites

  • Apicurio Registry is installed and running in your environment

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: 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:

    {"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"}]}
Additional resources

Managing artifact references using Apicurio Registry REST API commands

Apicurio Registry artifact types such as Apache Avro, Protobuf, and JSON Schema can include artifact references from one artifact file to another. You can create efficiencies by defining reusable schema and API artifacts, and then referencing them from multiple locations.

This section shows a simple curl-based example of using the Apicurio Registry core REST API 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:

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

  • Apicurio Registry is installed and running in your environment

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: 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:

    {"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":[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 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"}]
Additional resources

Exporting and importing registry content using Apicurio Registry REST API commands

As an administrator, you can use the Apicurio Registry REST API to export data from one Apicurio Registry instance and import it 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 v2 REST API to export and import existing registry 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 only import Apicurio Registry data that has been exported from another Apicurio Registry instance.
Prerequisites

  • 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 perserve unique IDs

Procedure

  1. Export the 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.

  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: http://my-target-registry:8080.

Additional resources