// Metadata created by nebel

[id="registry-overview"]
= {registry} overview

{registry} is a datastore for sharing standard event schemas and API designs across API and event-driven architectures. You can use {registry} to decouple the structure of your data from your client applications, and to share and manage your data types and API descriptions at runtime using a REST interface.

For example, client applications can dynamically push or pull the latest schema updates to or from the registry at runtime without needing to redeploy. Developer teams can query the registry for existing schemas required for services already deployed in production, and can register new schemas required for new services in development.  

You can enable client applications to use schemas and API designs stored in {registry} by specifying the registry URL in your client code. For example, the registry can store schemas used to serialize and deserialize messages, which can then be referenced from your client applications to ensure that the messages that they send and receive are compatible with those schemas.

Using {registry} to decouple your data structure from your applications reduces costs by decreasing overall message size, and creates efficiencies by increasing consistent reuse of schemas and API designs across your organization. {registry} provides a graphical user interface to make it easy for developers and administrators to manage registry content.


ifdef::rh-service-registry[]

{registry} is based on the Apicurio Registry open source community project. For details, see https://github.com/apicurio/apicurio-registry. 

endif::[]

[discrete]
== {registry} features
{registry} provides the following main features:

* Support for multiple payload formats for standard event schemas and API specifications 

ifdef::rh-service-registry[]
* Pluggable storage options including AMQ Streams, embedded Infinispan, or PostgreSQL database 
endif::[]
ifdef::apicurio-registry[]
* Pluggable storage options including Apache Kafka, embedded Infinispan, or PostgreSQL database 
endif::[]

* Registry content management by user interface, REST API command, Maven plug-in, or Java client

* Rules for content validation and version compatibility to govern how registry content evolves over time

* Full Apache Kafka schema registry support, including integration with Kafka Connect for external systems 

* Client serializers/deserializers (SerDes) to validate Kafka and other message types at runtime

* Cloud-native Quarkus Java runtime for low memory footprint and fast deployment times

* Compatibility with existing Confluent schema registry client applications

* Operator-based installation of {registry} on OpenShift

[id="registry-artifacts"]
= {registry} artifacts

The items stored in {registry}, such as event schemas and API specifications, are known as registry _artifacts_. The following shows an example of an Apache Avro schema artifact in JSON format for a simple share price application:

[source,json]
----
{
   "type": "record",
   "name": "price",
   "namespace": "com.example",
   "fields": [
       {
           "name": "symbol",
           "type": "string"
       },
       {
           "name": "price",
           "type": "string"
       }
   ]
}
----

When a schema or API contract is added as an artifact in the registry, client applications can then use that schema or API contract to validate that client messages conform to the correct data structure at runtime. 

{registry} supports a wide range of message payload formats for standard event schemas and API specifications. For example, supported formats include Apache Avro, Google protocol buffers, GraphQL, AsyncAPI, OpenAPI, and others. For more details, see xref:registry-artifact-types[].

[id="registry-rest-api"]
= Registry REST API
Using the Registry REST API, client applications can manage the artifacts in {registry}. This API provides create, read, update, and delete operations for:

Artifacts::
Manage the schema and API design artifacts stored in the registry. Also includes browse or search for artifacts, and manage the lifecycle state of an artifact: enabled, disabled, or deprecated. 
Artifact versions::
Manage the versions that are created when artifact content is updated. Also includes browse or search for versions, and manage the lifecycle state of a version: enabled, disabled, or deprecated.
Artifact metadata::
Manage details such as when the artifact was created, last updated, and so on.
Global rules::
Configure rules to govern the content evolution of all 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. 
Artifact rules::
Configure rules to govern the content evolution of a specific artifact to prevent invalid or incompatible content from being added to the registry. Artifact rules override any global rules configured. 

For detailed information, see the link:files/registry-rest-api.htm[Apicurio Registry REST API documentation].

.Compatibility with other schema registries
The Registry REST API is compatible with the Confluent schema registry REST API. This means that applications using Confluent client libraries can use {registry} instead as a drop-in replacement. 
ifdef::rh-service-registry[]
For more details, see link:https://developers.redhat.com/blog/2019/12/17/replacing-confluent-schema-registry-with-red-hat-integration-service-registry/[Replacing Confluent Schema Registry with Red Hat Integration Service Registry].
endif::[]

[id="registry-storage"]
= Storage options
{registry} provides the following underlying storage implementations for registry artifacts: 

ifdef::apicurio-registry[]

* In-memory 
* Java Persistence API 
* Apache Kafka 
* Apache Kafka Streams
* Embedded Infinispan cache

NOTE: The in-memory storage option is suitable for a development environment only. All data is lost when restarting this storage implementation. All other storage options are suitable for development and production environments.

For more details, see https://github.com/Apicurio/apicurio-registry. 

endif::[]

ifdef::rh-service-registry[]

.{registry} storage options
[%header,cols=2*] 
|===
|Storage option
|Release
|Kafka Streams storage in AMQ Streams 1.4 
|General Availability
|Embedded Infinispan storage in a cache
|Technical Preview only 
|Java Persistence API storage in a PostgreSQL 12 database
|Technical Preview only 
|===

endif::[]

ifdef::rh-service-registry[]
[IMPORTANT]
====
Infinispan and JPA storage are Technology Preview features only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. 

These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview.
====
endif::[]

For details on how to install into your preferred storage option, see xref:installing-the-registry[].

//The {registry} Operator enables you to install and configure {registry} with your selected storage implementation on OpenShift.

[id="client-serde"]
= Client serializers/deserializers 
Event-based producer applications can use serializers to encode messages that conform to a specific event schema. Consumer applications can then use deserializers to validate that messages have been serialized using the correct schema, based on a specific schema ID. 

.{registry} client serializer/deserializer architecture
image::images/getting-started/registry-serdes-architecture.png[Registry Serdes architecture]

{registry} provides client serializers/deserializers (Serdes) to validate the following message types at runtime:

* Apache Avro
* Google protocol buffers
* JSON Schema

The {registry} Maven repository and source code distributions include the serializer/deserializer implementations for these message types, which client developers can use to integrate with the registry. These implementations include custom `io.apicurio.registry.utils.serde` Java classes for each supported message type, which client applications can use to pull schemas from the registry at runtime for validation. 

ifdef::rh-service-registry[]
.Additional resources
For instructions on how to use the {registry} client serializer/deserializer for Apache Avro in AMQ Streams producer and consumer applications, see
link:https://access.redhat.com/documentation/en-us/red_hat_amq/{amq-version}/html/using_amq_streams_on_openshift/service-registry-str[Using AMQ Streams on Openshift].

endif::[]


[id="kafka-connect"]
= Kafka Connect converters 
{registry} supports Apache Kafka Connect for streaming data between Kafka and other systems. You can use Kafka Connect to define connectors for different systems to move large volumes of data into and out of Kafka-based systems. 

{registry} provides the following features for Kafka Connect:

* Storage for Kafka Connect schemas
* Kafka Connect converters for Apache Avro and JSON schemas

You can use these Avro and JSON schema converters to map Kafka Connect schemas into Avro or JSON schemas. Those schemas can then serialize message keys and values into the compact Avro binary format or human-readable JSON format. The converted JSON is also less verbose because the messages do not contain the schema information, only the schema ID.

{registry} can manage and track the schemas used in Kafka topics, and where the Avro or JSON converter sends the generated Avro or JSON schemas. Because the schemas are stored in {registry}, each message must only include a tiny schema identifier. For an I/O bound system like Kafka, this means more total throughput for producers and consumers.

The Avro and JSON schema serializers and deserializers (Serdes) provided by {registry} are also used by Kafka producers and consumers in this use case. Kafka consumer applications that you write to consume change events can use the Avro or JSON Serdes to deserialize these change events. You can install these Serdes into any Kafka-based distribution and use them along with Kafka Connect and Debezium.

.Additional resources

* link:https://kafka.apache.org/documentation/#connect[Apache Kafka Connect documentation]
* link:https://access.redhat.com/documentation/en-us/red_hat_integration/2020-04/html/debezium_user_guide/index[Debezium User Guide]
//* link:{LinkCDCUserGuide}#avro-serialization[Avro serialization]  
* link:https://debezium.io/blog/2020/04/09/using-debezium-wit-apicurio-api-schema-registry/[Demonstration of using Kakfa Connect with Debezium and Apicurio Registry]


[id="registry-demo"]
= Registry demonstration examples
{registry} provides an open source demonstration example of Apache Avro serialization/deserialization with storage in Apache Kafka Streams. This example shows how the serializer/deserializer obtains the Avro schema from the registry at runtime and uses it to serialize and deserialize Kafka messages. For more details, see link:https://github.com/Apicurio/apicurio-registry-demo[].

This demonstration also provides simple examples of both Avro and JSON Schema serialization/deserialization with storage in Apache Kafka:
https://github.com/Apicurio/apicurio-registry-demo/tree/master/src/main/java/io/apicurio/registry/demo/simple

ifdef::rh-service-registry[]
For another demonstration example with detailed instructions on Avro serialization/deserialization with storage in Apache Kafka, see the Red Hat Developer article on link:https://developers.redhat.com/blog/2019/12/16/getting-started-with-red-hat-integration-service-registry/[Getting Started with Red Hat Integration Service Registry].
endif::[]

[id="registry-distros"]
= Available distributions

You can access the following available distributions for {registry}: 

ifdef::apicurio-registry[]

.{registry} distributions 
[%header,cols=2*] 
|===
|Storage option
|Container Image
|In-memory
|https://hub.docker.com/r/apicurio/apicurio-registry-mem
|Java Persistence API  
|https://hub.docker.com/r/apicurio/apicurio-registry-jpa 
|Apache Kafka
|https://hub.docker.com/r/apicurio/apicurio-registry-kafka 
|Apache Kafka Streams
|https://hub.docker.com/r/apicurio/apicurio-registry-streams
|Infinispan
|https://hub.docker.com/r/apicurio/apicurio-registry-infinispan
|===

.Additional resources
* For details on building from source code, see https://github.com/Apicurio/apicurio-registry.

endif::[]

ifdef::rh-service-registry[]

.{registry} distributions
[%header,cols="3,3,2"]
|===
|Distribution
|Location
|Release
|OpenShift Operator for Kafka storage in AMQ Streams 
|OpenShift web console under *Operators* → *OperatorHub*
|General Availability
|Container image for Kafka storage in AMQ Streams 
|link:{download-url-registry-container-catalog}[Red Hat Container Catalog]
|General Availability
|Container image for embedded Infinispan storage 
|link:{download-url-registry-container-catalog}[Red Hat Container Catalog]
|Technical Preview only
|Container image for JPA storage in PostgreSQL 
|link:{download-url-registry-container-catalog}[Red Hat Container Catalog]
|Technical Preview only
|Maven repository .zip
|link:{download-url-registry-maven}[Software Downloads for Red Hat Integration]
|General Availability
|Full Maven repository .zip (with all dependencies) 
|link:{download-url-registry-maven-full}[Software Downloads for Red Hat Integration]
|General Availability
|Source code .zip
|link:{download-url-registry-source-code}[Software Downloads for Red Hat Integration]
|General Availability
|Kafka Connect converters .zip 
|link:{download-url-registry-kafka-connect}[Software Downloads for Red Hat Integration]
|General Availability
|===

NOTE: You must have a subscription for Red Hat Integration and be logged into the Red Hat Customer Portal to access the available {registry} distributions.
endif::[]
