Managing Service Registry data using the core REST API

Guide
  • Red Hat OpenShift Service Registry 1
  • Updated 07 December 2021
  • Published 24 September 2021

Managing Service Registry data using the core REST API

Guide
Red Hat OpenShift Service Registry 1
  • Updated 07 December 2021
  • Published 24 September 2021

Manage schemas and API artifacts stored in the Red Hat OpenShift Service Registry cloud service using the registry core REST API.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code and documentation. We are beginning with these four terms: master, slave, blacklist, and whitelist. Due to the enormity of this endeavor, these changes will be gradually implemented over upcoming releases. For more details on making our language more inclusive, see our CTO Chris Wright’s message.

Service Registry core REST API

Client applications can use the Using the Service Registry core v2 REST API to manage the schema and API artifacts in Service 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 labels. 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 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

Service Registry provides compatibility with the following schema registries by including implementations of their respective REST APIs:

  • Service Registry core v1

  • Confluent Schema Registry v6

  • CNCF CloudEvents Schema Registry v0

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

Additional resources

Creating an access token for Service Registry REST API commands

This section shows a curl-based example of how to create an OAuth Bearer access token for use with the Service Registry core REST API. You can do this using the OpenShift Application Services authentication server and your service account credentials.

Prerequisites
  • You have access to the Service Registry web console

Procedure
  1. Create your service account credentials using the web console:

    https://console.redhat.com/application-services/service-accounts

  2. Copy the generated Client ID and Client Secret to a secure location.

  3. Create an OAuth Bearer token using your service account client ID and secret:

    $ curl -X POST \
      -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET" \
      https://identity.api.openshift.com/auth/realms/rhoas/protocol/openid-connect/token
  4. Copy the access token generated in the response to a secure location:

    {"access_token":"eyJhbG........a3BQ","expires_in":300,"refresh_expires_in":0,"token_type":"bearer","not-before-policy":0,"scope":"profile email"}
  5. Set an ACCESS_TOKEN environment variable to the contents of this generated access token:

    export ACCESS_TOKEN=VALUE

Managing schema and API artifacts using Service Registry REST API commands

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

Prerequisites
  • You have a service account with the correct access permissions for Service Registry instances.

  • You have created an access token using your service account credentials.

Procedure
  1. Connect to the Service Registry web console on:

    https://console.redhat.com/beta/application-services/service-registry/

  2. For the relevant Service Registry instance that you want to connect to, select the options icon (three vertical dots) and click Connection.

  3. In the Connection page, copy the URL for the Core Registry API to a secure location. This is the registry API endpoint that you need for connecting to this Service Registry instance.

  4. 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"}]}' \
      http://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, Service Registry generates one automatically as a UUID.

    • MY-REGISTRY-URL is the URL on which Service Registry is deployed. For example: https://service-registry.apps.app-sre-0.k3s7.p1.openshiftapps.com/t/f301375a-18a7-426c-bbd8-8e626a0a1d0e.

    • 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.

  5. 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.

  6. 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" \
     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 Service Registry REST API commands

If you do not specify an artifact version when adding schema and API artifacts to Service Registry using the v2 core REST API, Service Registry generates one 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 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
  • You have a service account with the correct access permissions for Service Registry instances.

  • You have created an access token using your service account credentials.

Procedure
  1. Connect to the Service Registry web console on:

    https://console.redhat.com/beta/application-services/service-registry/

  2. For the relevant Service Registry instance that you want to connect to, select the options icon (three vertical dots) and click Connection.

  3. In the Connection page, copy the URL for the Core Registry API to a secure location. This is the registry API endpoint that you need for connecting to this Service Registry instance.

  4. 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"}]}' \
       http://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 URL on which Service Registry is deployed. For example: https://service-registry.apps.app-sre-0.k3s7.p1.openshiftapps.com/t/f301375a-18a7-426c-bbd8-8e626a0a1d0e.

    • 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.

  5. 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.

  6. 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" \
    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 Service 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 Service Registry instance to another. For example, this is useful when migrating or upgrading from one Service Registry v2.x instance to another.

You can import Service Registry data that has been exported from another Red Hat OpenShift Streams for Apache Kafka instance. You cannot currently import Service Registry data from a Red Hat Integration Service Registry instance.
Prerequisites
  • You have a service account with the correct access permissions for Service Registry instances.

  • You have created an access token using your service account credentials.

Procedure
  1. Connect to the Service Registry web console on:

    https://console.redhat.com/beta/application-services/service-registry/

  2. For the relevant Service Registry instance that you want to connect to, select the options icon (three vertical dots) and click Connection.

  3. In the Connection page, copy the URL for the Core Registry API to a secure location. This is the registry API endpoint that you need for connecting to this Service Registry instance.

  4. Export the registry data from your existing source Service Registry instance:

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

    MY-REGISTRY-URL is the URL on which the source Service Registry is deployed. For example: https://service-registry-source.apps.app-sre-0.k3s7.p1.openshiftapps.com/t/f301375a-18a7-426c-bbd8-8e626a0a1d0e.

  5. Import the registry data into your target Service Registry instance:

    $ curl -X POST "http://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 URL on which the target Service Registry is deployed. For example: https://service-registry-target.apps.app-sre-0.k3s7.p1.openshiftapps.com/t/f301375a-18a7-426c-bbd8-8e626a0a1d0e.

Additional resources