Chapter 4. Managing Service Registry content using the REST API

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" \ 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, Service Registry generates one automatically as a UUID.

   2

   MY-REGISTRY-HOST is the host name on which Service Registry is deployed. For example: my-cluster-service-registry-myproject.example.com.

   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 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"}]}

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" \ 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 a version, Service Registry automatically generates a default version of 1.

   2

   MY-REGISTRY-HOST is the host name on which Service Registry is deployed. For example: my-cluster-service-registry-myproject.example.com.

   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 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 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"}]}

Procedure

1. Export the registry data from your existing source Service 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 Service Registry is deployed. For example: my-cluster-source-registry-myproject.example.com.

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

   $ curl -X POST "http://MY-REGISTRY-HOST/apis/registry/v2/admin/import" \
     -H "Content-Type: application/zip" --data-binary @my-registry-data.zip

   MY-REGISTRY-HOST is the host name on which the target Service Registry is deployed. For example: my-cluster-target-registry-myproject.example.com.