Chapter 6. Managing Service Registry content using the REST API

PDF

This chapter explains how to manage artifacts stored in the registry using the Registry REST API. This includes using Registry REST API commands, a Maven plug-in, or a Java client application:

6.1. Managing artifacts using Registry REST API commands

Client applications can use Registry REST API commands to manage artifacts in Service 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 section shows a simple curl-based example of using the Registry REST API to add and retrieve an Apache Avro schema artifact in the registry.

Note

When adding artifacts in Service Registry using the REST API, if you do not specify a unique artifact ID, Service Registry generates one automatically as a UUID.

Prerequisites

See Section 1.4, “Registry REST API”.
Service Registry must be installed and running in your environment. For details, see Chapter 3, Installing Service Registry on OpenShift.

Procedure

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" --data '{"type":"record","name":"price","namespace":"com.example","fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' http://MY-REGISTRY-HOST/api/artifacts
```
This example shows adding an Avro schema artifact with an artifact ID of share-price.
MY-REGISTRY-HOST is the host name on which Service Registry is deployed. For example: my-cluster-service-registry-myproject.example.com.

Verify that the response includes the expected JSON body to confirm that the artifact was added. For example:

{"createdOn":1578310374517,"modifiedOn":1578310374517,"id":"share-price","version":1,"type":"AVRO","globalId":8}

Retrieve the artifact from the registry using its artifact ID. For example, in this case the specified ID is share-price:

$ curl http://MY-REGISTRY-URL/api/artifacts/share-price
'{"type":"record","name":"price","namespace":"com.example","fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}

Additional resources

For more REST API sample requests, see the Registry REST API documentation.

6.2. Managing artifacts using the Service Registry Maven plug-in

Service Registry provides a Maven plug-in to enable you to upload or download registry artifacts as part of your development build. For example, this plug-in is useful for testing and validating that your schema updates are compatible with client applications.

Prerequisites

Service Registry must be installed and running in your environment
Maven must be installed and configured in your environment

Procedure

Update your Maven pom.xml file to use the apicurio-registry-maven-plugin to upload an artifact to Service Registry. The following example shows registering an Apache Avro schema artifact:

<plugin>
<groupId>io.apicurio</groupId>
<artifactId>apicurio-registry-maven-plugin</artifactId>
<version>${registry.version}</version>
<executions>
  <execution>
    <phase>generate-sources</phase>
    <goals>
      <goal>register</goal> 1
    </goals>
    <configuration>
      <registryUrl>http://my-cluster-service-registry-myproject.example.com/api</registryUrl> 2
      <artifactType>AVRO</artifactType>
      <artifacts>
        <schema1>${project.basedir}/schemas/schema1.avsc</schema1> 3
      </artifacts>
    </configuration>
  </execution>
</executions>
</plugin>

1: Specify register as the execution goal to upload an artifact to the registry.
2: You must specify the Service Registry URL with the /api endpoint.
3: You can upload multiple artifacts using the artifact ID and location.

You can also update your Maven pom.xml file to download a previously registered artifact from Service Registry:

<plugin>
<groupId>io.apicurio</groupId>
<artifactId>apicurio-registry-maven-plugin</artifactId>
<version>${registry.version}</version>
<executions>
  <execution>
    <phase>generate-sources</phase>
    <goals>
      <goal>download</goal> 1
    </goals>
    <configuration>
      <registryUrl>http://my-cluster-service-registry-myproject.example.com/api</registryUrl> 2
          <ids>
            <param1>schema1</param1> 3
          </ids>
      <outputDirectory>${project.build.directory}</outputDirectory>
   </configuration>
 </execution>
</executions>
</plugin>

1: Specify download as the execution goal.
2: You must specify the Service Registry URL with the /api endpoint.
3: You can download multiple artifacts to a specified directory using the artifact ID.

Additional resources

For more details on the Maven plug-in, see https://github.com/Apicurio/apicurio-registry-demo.

6.3. Managing artifacts using a Service Registry client application

You can also manage artifacts stored in Service Registry using a Java client application. You create, read, update, or delete artifacts stored in the registry using the Service Registry Java client classes.

Prerequisites

See Section 1.6, “Kafka client serializers/deserializers”
You must have implemented a client application in Java that imports the Service Registry client classes: io.apicurio.registry.client.RegistryClient
Service Registry must be installed and running in your environment

Procedure

Update your client application to add a new artifact in the registry. The following example shows adding an Apache Avro schema artifact from a Kafka producer client application:

String registryUrl_node1 = PropertiesUtil.property(clientProperties, "registry.url.node1",
  "http://my-cluster-service-registry-myproject.example.com/api"); 1
   try (RegistryService service = RegistryClient.create(registryUrl_node1))
   {
    String artifactId = ApplicationImpl.INPUT_TOPIC + "-value";
    try {
     service.getArtifactMetaData(artifactId); 2
    }
    catch (WebApplicationException e) {
     CompletionStage < ArtifactMetaData > csa = service.createArtifact( 3
        ArtifactType.AVRO,
        artifactId,
         new ByteArrayInputStream(LogInput.SCHEMA$.toString().getBytes())
        );
    csa.toCompletableFuture().get();
    }
 }

1: Configure the client application with the Service Registry URL in the client properties. You must specify the Service Registry URL with the /api endpoint. You can create properties for more than one registry node.
2: Check to see if the schema artifact already exists in the registry based on the artifact ID.
3: Add the new schema artifact in the registry.

Additional resources

For an example Java client application, see https://github.com/Apicurio/apicurio-registry-demo.
For details on how to use the Service Registry Kafka client serializer/deserializer for Apache Avro in AMQ Streams producer and consumer applications, see Using AMQ Streams on Openshift.

Chapter 6. Managing Service Registry content using the REST API

6.1. Managing artifacts using Registry REST API commands

6.2. Managing artifacts using the Service Registry Maven plug-in

6.3. Managing artifacts using a Service Registry client application

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links