Chapter 4. Managing artifacts in Service Registry
This chapter provides details on different approaches to managing artifacts in Service Registry:
4.1. Managing artifacts using the Registry REST API
The Registry REST API enables client applications to manage artifacts in the registry, for example, in a CI/CD pipeline deployed in production. This REST API provides create, read, update, and delete operations for artifacts, versions, metadata, and rules stored in the registry.
When creating 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.
This chapter shows a simple curl-based example of using the Registry REST API to create and retrieve a Apache Avro schema artifact in the registry.
Prerequisites
- See Section 1.1.2, “Registry REST API”.
- Service Registry must be installed and running in your environment. For details, see Chapter 3, Installing Service Registry.
Procedure
Create an artifact in the registry using the
/artifactsoperation. The following examplecurlcommand creates 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/artifactsThis example shows creating an Avro schema artifact with an artifact ID of
share-price.MY-REGISTRY-HOSTis 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 created. 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 https://MY-REGISTRY-URL/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.
4.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.xmlfile to use theapicurio-registry-maven-pluginto upload an artifact. 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>https://my-cluster-service-registry-myproject.example.com</registryUrl> 2 <artifactType>AVRO</artifactType> <artifacts> <schema1>${project.basedir}/schemas/schema1.avsc</schema1> 3 </artifacts> </configuration> </execution> </executions> </plugin>You can also update your Maven
pom.xmlfile to download a previously registered artifact:<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>https://my-cluster-service-registry-myproject.example.com</registryUrl> 2 <ids> <param1>schema1</param1> 3 </ids> <outputDirectory>${project.build.directory}</outputDirectory> </configuration> </execution> </executions> </plugin>
Additional resources
- For more details on the Maven plug-in, see https://github.com/Apicurio/apicurio-registry-demo.
4.3. Managing artifacts in a Java client application
You can also manage artifacts in the registry using a Java client application. The Service Registry Java client classes enable you to create, read, update, or delete artifacts in the registry.
Prerequisites
- See Section 1.1.5, “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 create a new artifact in the registry. The following example shows creating an Apache Avro schema artifact from a Kafka producer client application:
String registryUrl_node1 = PropertiesUtil.property(clientProperties, "registry.url.node1", "https://my-cluster-service-registry-myproject.example.com"); 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(); } }
Additional resources
- For an example Java client application, see https://github.com/Apicurio/apicurio-registry-demo.
- For more details on Kafka client applications, see: Using AMQ Streams on OpenShift.
