Apicurio Studio

Managing Apicurio Registry content using the REST API

Client applications can use Registry REST API commands 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:

Registry core REST API overview

Using the Apicurio Registry core REST API, client applications can manage the schema and API artifacts in Apicurio Registry. This API provides create, read, update, and delete operations for:

Artifacts

Manage schema and API artifacts stored in the registry. You can also manage the lifecycle state of an artifact: enabled, disabled, or deprecated.

Artifact versions

Manage versions that are created when a schema or API artifact is updated. You can also manage the lifecycle state of an artifact version: enabled, disabled, or deprecated.

Artifact metadata

Manage details about a schema or API artifact, such as when it was created or modified, and its current state. You can edit the artifact name, description, or label. The artifact group and when the artifact was created or modified are read-only.

Artifact rules

Configure rules to govern the content evolution of a specific schema or API artifact to prevent invalid or incompatible content from being added to the registry. Artifact rules override any global rules configured.

Global rules

Configure rules to govern the content evolution of all schema and API artifacts artifacts to prevent invalid or incompatible content from being added to the registry. Global rules are applied only if an artifact does not have its own specific artifact rules configured.

Search

Browse or search for schema and API artifacts and versions, for example, by name, group, description, or label.

Admin

Export or import registry content in a .zip file, and manage logging levels for the registry server instance at runtime.

Compatibility with other schema registry REST APIs

The Apicurio Registry core REST API version 2.0 is compatible with the following schema registry APIs:

  • Apicurio Registry core REST API version 1

  • Confluent schema registry version 6

  • IBM schema registry version 1

  • Cloud Native Computing Foundation schema registry version 0

Applications using Confluent client libraries can use Apicurio Registry as a drop-in replacement.

Additional resources
  • For detailed information, see the Apicurio Registry REST API documentation.

  • API documentation for the core Apicurio Registry REST API and for all compatible APIs is available from the main endpoint of your Apicurio Registry deployment, for example, on http://MY-REGISTRY-URL/apis.

Managing schema and API artifacts using Registry REST API commands

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

Prerequisites
  • Apicurio Registry must be installed and running in your environment.

Procedure
  1. Add an artifact in the registry using the /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" \ (1)
      --data '{"type":"record","name":"price","namespace":"com.example", \
       "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' \ (2)
      http://MY-REGISTRY-HOST/apis/registry/v2/groups/my-group/artifacts (3)
    1 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.
    2 MY-REGISTRY-HOST is the host name on which Apicurio Registry is deployed. For example: http://localhost:8080.
    3 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", (1)
    "type":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2} (2)
    1 No version was specified when adding the artifact, so the default version 1 is created automatically.
    2 This was the second artifact added to the registry, so the global ID and content ID have a default 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 http://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 Registry REST API commands

If you do not specify an artifact version when adding schema and API artifacts to Apicurio Registry using the v2 REST API, Apicurio Registry generates one automatically. The default version when adding an artifact is 1.

However, Apicurio Registry also supports custom versioning where you can specify a version using the X-Registry-Version HTTP request header as a string. You can then use this version value when executing REST API operations that require the artifact 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 artifact 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 must be installed and running in your environment.

Procedure
  1. Add an artifact version in the registry using the /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" \ (1)
      --data '{"type":"record","name":" p","namespace":"com.example", \
       "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' \ (2)
       http://MY-REGISTRY-HOST/apis/registry/v2/groups/my-group/artifacts (3)
    1 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 version, Apicurio Registry automatically generates a default version of 1.
    2 MY-REGISTRY-HOST is the host name on which Apicurio Registry is deployed. For example: http://localhost:8080.
    3 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", (1)
    "type":"AVRO","globalId":3,"state":"ENABLED","groupId":"my-group","contentId":3} (2)
    1 A custom version was of 1.1.1 was specified when adding the artifact.
    2 This was the third artifact added to the registry, so the global ID and content ID have a default 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 http://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

Exporting and importing registry content using Registry REST API commands

This section shows a simple curl-based example of using the registry v2 core REST API to export and import existing registry data in .zip format from one Apicurio Registry instance to another. For example, this is useful when migrating and upgrading from an existing Apicurio Registry instance to another.

Prerequisites
  • Apicurio Registry must be installed and running in your environment.

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

    $ curl http://MY-REGISTRY-HOST/apis/registry/v2/admin/export \
      --output my-registry-data.zip

    MY-REGISTRY-HOST 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 "http://MY-REGISTRY-HOST/apis/registry/v2/admin/import" \
      -H "Accept: application/json" -H "Content-Type: application/zip" \
      --data-binary @my-registry-data.zip

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

Additional resources