diff --git a/docs-playbook/Dockerfile b/docs-playbook/Dockerfile index b317bff7c0..847a2fc3bd 100644 --- a/docs-playbook/Dockerfile +++ b/docs-playbook/Dockerfile @@ -4,8 +4,8 @@ FROM ubuntu:latest ENV BASE_DIR=/repository/docs-playbook -ENV PLAYBOOK docs-playbook.yml -ENV SEARCH_PLAYBOOK search-playbook.yml +ENV PLAYBOOK=docs-playbook.yml +ENV SEARCH_PLAYBOOK=search-playbook.yml VOLUME /repository diff --git a/docs-playbook/_build-all-local.sh b/docs-playbook/_build-all-local.sh new file mode 100755 index 0000000000..9e6da1db90 --- /dev/null +++ b/docs-playbook/_build-all-local.sh @@ -0,0 +1,7 @@ +#!/bin/sh + +# Build the docker image +docker build -t="apicurio/apicurio-docs-builder" --rm . + +# Use the docker image to build the docs +docker run --env PLAYBOOK=local-test-playbook.yml --env SEARCH_PLAYBOOK=local-test-playbook.yml -v $(pwd)/..:/repository apicurio/apicurio-docs-builder:latest diff --git a/docs-playbook/docs-playbook.yml b/docs-playbook/docs-playbook.yml index befed11ffa..622aeaa951 100644 --- a/docs-playbook/docs-playbook.yml +++ b/docs-playbook/docs-playbook.yml @@ -6,7 +6,7 @@ site: content: sources: - url: https://github.com/Apicurio/apicurio-registry.git - branches: 2.6.x,2.5.x,2.4.x,2.3.x,2.2.x,2.1.x,2.0.x,1.3.x + branches: main,2.6.x,2.5.x,2.4.x,2.3.x,2.2.x,2.1.x,2.0.x,1.3.x start_path: docs edit_url: '{web_url}' - url: https://github.com/Apicurio/apicurio-registry-operator.git diff --git a/docs-playbook/local-test-playbook.yml b/docs-playbook/local-test-playbook.yml new file mode 100644 index 0000000000..a7fe23b4d1 --- /dev/null +++ b/docs-playbook/local-test-playbook.yml @@ -0,0 +1,41 @@ +site: + title: Apicurio Registry PREVIEW + # the 404 page and sitemap files only get generated when the url property is set + url: https://www.apicur.io/registry/docs + start_page: apicurio-registry::index.adoc +content: + sources: + - url: ../ + branches: HEAD + start_path: docs + +ui: + bundle: + url: https://raw.githubusercontent.com/Apicurio/apicurio-docs-ui/main/dist/ui-bundle.zip + snapshot: true + +runtime: + cache_dir: ./target/antora-cache + +output: + dir: ./target/dist + +asciidoc: + attributes: + plantuml-server-url: 'http://www.plantuml.com/plantuml' + plantuml-fetch-diagram: true + mod-loc: partial$ + registry-overview: link:assembly-intro-to-the-registry.html[Introduction to Apicurio Registry] + registry-rules: link:assembly-intro-to-registry-rules.html[Introduction to Apicurio Registry rules] + registry-artifact-reference: link:assembly-artifact-reference.html[Apicurio Registry artifact reference] + registry-rule-reference: link:assembly-rule-reference.html[Apicurio Registry rule reference] + registry-config-reference: link:assembly-config-reference.html[Apicurio Registry configuration reference] + installing-the-registry-docker: link:assembly-installing-registry-docker.html[Installing Apicurio Registry using Docker] + installing-the-registry-openshift: link:assembly-installing-registry-openshift.html[Installing Apicurio Registry on OpenShift] + installing-the-registry-storage-openshift: link:assembly-installing-registry-storage-openshift.html[Installing Apicurio Registry storage on OpenShift] + managing-registry-artifacts-ui: link:assembly-managing-registry-artifacts-ui.html[Managing Apicurio Registry content using the web console] + managing-registry-artifacts-api: link:assembly-managing-registry-artifacts-api.html[Managing Apicurio Registry content using the REST API] + managing-registry-artifacts-maven: link:assembly-managing-registry-artifacts-maven.html[Managing Apicurio Registry content using the Maven plug-in] + sdk: link:assembly-using-the-registry-sdk.html[Managing Apicurio Registry content using an SDK] + kafka-client-serdes: link:assembly-using-kafka-client-serdes.html[Validating schemas using Kafka client serializers/deserializers in Java clients] + registry-client-serdes-config: link:assembly-configuring-kafka-client-serdes.html[Configuring Kafka serializers/deserializers in Java applications] diff --git a/docs-playbook/package.json b/docs-playbook/package.json index def50ca997..d6adba23c2 100644 --- a/docs-playbook/package.json +++ b/docs-playbook/package.json @@ -1,6 +1,6 @@ { "name": "apicurio-docs-playbook", - "version": "1.0.0", + "version": "3.0.0", "description": "This folder contains the configuration and scripts used when building the Apicurio Registry documentation for publishing to the Apicurio project web site. We are using a tool called Antora to build the asciidoc based documentation into a publishable site. However, due to some issues with building on various platforms (I'm looking at you, Windows) and also some conflicts between what Antora builds and what our GitHub Pages (jekyll) project site expects, we have created a non-trivial (but automated) process for building the docs.", "main": "index.js", "scripts": { diff --git a/docs-playbook/search-playbook.yml b/docs-playbook/search-playbook.yml index 025002851e..57e956031a 100644 --- a/docs-playbook/search-playbook.yml +++ b/docs-playbook/search-playbook.yml @@ -6,7 +6,7 @@ site: content: sources: - url: https://github.com/Apicurio/apicurio-registry.git - branches: 2.6.x + branches: main start_path: docs edit_url: '{web_url}' - url: https://github.com/Apicurio/apicurio-registry-operator.git diff --git a/docs/getting-started/master.adoc b/docs/getting-started/master.adoc index cab7825105..2287f4609b 100644 --- a/docs/getting-started/master.adoc +++ b/docs/getting-started/master.adoc @@ -27,5 +27,5 @@ include::assemblies/getting-started/assembly-all-registry-configurations.adoc[le include::assemblies/getting-started/assembly-managing-registry-artifacts-ui.adoc[leveloffset=+1] include::assemblies/getting-started/assembly-managing-registry-artifacts-api.adoc[leveloffset=+1] include::assemblies/getting-started/assembly-using-kafka-client-serdes.adoc[leveloffset=+1] -include::assemblies/getting-started/assembly-using-the-registry-client.adoc[leveloffset=+1] +include::assemblies/getting-started/assembly-using-the-registry-sdk.adoc[leveloffset=+1] include::assemblies/getting-started/assembly-registry-reference.adoc[leveloffset=+1] diff --git a/docs/local-test-playbook.yml b/docs/local-test-playbook.yml index 9380236070..a7fe23b4d1 100644 --- a/docs/local-test-playbook.yml +++ b/docs/local-test-playbook.yml @@ -36,6 +36,6 @@ asciidoc: managing-registry-artifacts-ui: link:assembly-managing-registry-artifacts-ui.html[Managing Apicurio Registry content using the web console] managing-registry-artifacts-api: link:assembly-managing-registry-artifacts-api.html[Managing Apicurio Registry content using the REST API] managing-registry-artifacts-maven: link:assembly-managing-registry-artifacts-maven.html[Managing Apicurio Registry content using the Maven plug-in] - rest-client: link:assembly-using-the-registry-client.html[Managing Apicurio Registry content using a Java client] + sdk: link:assembly-using-the-registry-sdk.html[Managing Apicurio Registry content using an SDK] kafka-client-serdes: link:assembly-using-kafka-client-serdes.html[Validating schemas using Kafka client serializers/deserializers in Java clients] - registry-client-serdes-config: link:assembly-configuring-kafka-client-serdes.html[Configuring Kafka serializers/deserializers in Java clients] + registry-client-serdes-config: link:assembly-configuring-kafka-client-serdes.html[Configuring Kafka serializers/deserializers in Java applications] diff --git a/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-artifact-branches.png b/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-artifact-branches.png new file mode 100644 index 0000000000..36ffe9be7b Binary files /dev/null and b/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-artifact-branches.png differ diff --git a/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-artifact-rules.png b/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-artifact-rules.png new file mode 100644 index 0000000000..aa2359cd87 Binary files /dev/null and b/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-artifact-rules.png differ diff --git a/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-artifact-version.png b/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-artifact-version.png new file mode 100644 index 0000000000..b07c9f4f13 Binary files /dev/null and b/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-artifact-version.png differ diff --git a/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-artifact.png b/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-artifact.png index 0e79581ca9..f7d70dc60c 100644 Binary files a/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-artifact.png and b/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-artifact.png differ diff --git a/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-client-sdk.png b/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-client-sdk.png deleted file mode 100644 index 305ea31dc0..0000000000 Binary files a/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-client-sdk.png and /dev/null differ diff --git a/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-global-rules.png b/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-global-rules.png new file mode 100644 index 0000000000..f28241a8a6 Binary files /dev/null and b/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-global-rules.png differ diff --git a/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-group-rules.png b/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-group-rules.png new file mode 100644 index 0000000000..21c5fcd7d0 Binary files /dev/null and b/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-group-rules.png differ diff --git a/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-rules.png b/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-rules.png deleted file mode 100644 index e71559ce4b..0000000000 Binary files a/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console-rules.png and /dev/null differ diff --git a/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console.png b/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console.png index 22ceaa63f5..f0e6c483c2 100644 Binary files a/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console.png and b/docs/modules/ROOT/assets/images/images/getting-started/registry-web-console.png differ diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index a1727073b7..86372b590b 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -7,7 +7,7 @@ ** xref:getting-started/assembly-installing-registry-storage-openshift.adoc[] ** link:https://www.apicur.io/registry/docs/apicurio-registry-operator/1.0.0/index.html[Apicurio Registry Operator documentation] * Migration -** xref:getting-started/assembly-migrating-registry-v1-v2.adoc[] +** xref:getting-started/assembly-migrating-registry-v2-v3.adoc[] * Configuration ** xref:getting-started/assembly-configuring-registry-security.adoc[] ** xref:getting-started/assembly-configuring-the-registry.adoc[] diff --git a/docs/modules/ROOT/pages/getting-started/assembly-artifact-reference.adoc b/docs/modules/ROOT/pages/getting-started/assembly-artifact-reference.adoc index 6aaddc6e6f..58c30ea221 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-artifact-reference.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-artifact-reference.adoc @@ -10,7 +10,9 @@ This chapter provides reference information on the supported artifact types, sta * xref:registry-artifact-types_{context}[] * xref:registry-artifact-states_{context}[] +* xref:registry-group-metadata_{context}[] * xref:registry-artifact-metadata_{context}[] +* xref:registry-artifact-version-metadata_{context}[] [role="_additional-resources"] .Additional resources @@ -19,4 +21,6 @@ This chapter provides reference information on the supported artifact types, sta //INCLUDES include::{mod-loc}getting-started/ref-registry-artifact-types.adoc[leveloffset=+1] include::{mod-loc}getting-started/ref-registry-artifact-states.adoc[leveloffset=+1] +include::{mod-loc}getting-started/ref-registry-group-metadata.adoc[leveloffset=+1] include::{mod-loc}getting-started/ref-registry-artifact-metadata.adoc[leveloffset=+1] +include::{mod-loc}getting-started/ref-registry-artifact-version-metadata.adoc[leveloffset=+1] diff --git a/docs/modules/ROOT/pages/getting-started/assembly-configuring-the-registry.adoc b/docs/modules/ROOT/pages/getting-started/assembly-configuring-the-registry.adoc index 4e1826abd7..5308bb24dd 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-configuring-the-registry.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-configuring-the-registry.adoc @@ -5,13 +5,11 @@ include::{mod-loc}shared/all-attributes.adoc[] = Configuring your {registry} deployment [role="_abstract"] -This chapter explains how to set important configuration options for your {registry} deployment. This includes features such as the {registry} web console, logging, events, and health checks: +This chapter explains how to set important configuration options for your {registry} deployment. This includes features such as the {registry} web console, logging, and health checks: ifdef::apicurio-registry[] * xref:configuring-registry-ui_{context}[] endif::[] -* xref:registry-logging_{context}[] -* xref:registry-cloud-events_{context}[] * xref:configuring-liveness-readiness-probes_{context}[] * xref:registry-liveness-env-vars_{context}[] @@ -21,7 +19,5 @@ NOTE: For a list of all available configuration options, see {registry-config-re ifdef::apicurio-registry[] include::{mod-loc}getting-started/proc-configuring-registry-ui.adoc[leveloffset=+1] endif::[] -include::{mod-loc}getting-started/proc-configuring-registry-logging.adoc[leveloffset=+1] -include::{mod-loc}getting-started/proc-configuring-registry-events.adoc[leveloffset=+1] include::{mod-loc}getting-started/proc-configuring-liveness-readiness-probes.adoc[leveloffset=+1] include::{mod-loc}getting-started/ref-registry-liveness-env-vars.adoc[leveloffset=+1] diff --git a/docs/modules/ROOT/pages/getting-started/assembly-installing-registry-docker.adoc b/docs/modules/ROOT/pages/getting-started/assembly-installing-registry-docker.adoc index 3c32d4bf12..627a8a5c0f 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-installing-registry-docker.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-installing-registry-docker.adoc @@ -14,7 +14,7 @@ This chapter explains how to install and run {registry} using Docker with the fo .Prerequisites * {registry-overview} -NOTE: You can install more than one instance of {registry} depending on your environment. The number of instances depends on your storage option, for example, your Kafka or database cluster configuration, and on the number and type of artifacts stored in {registry}. +NOTE: You can install more than one replica of {registry} depending on your environment. The number of replicas depends on your storage option, for example, your Kafka or database cluster configuration, and on the number and type of artifacts stored in {registry}. [role="_additional-resources"] .Additional resources diff --git a/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-api.adoc b/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-api.adoc index b0ef5d77cb..03548b1895 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-api.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-api.adoc @@ -6,13 +6,10 @@ include::{mod-loc}shared/all-attributes.adoc[] //If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring. [role="_abstract"] -Client applications can use {registry} REST API operations to manage schema and API artifacts in {registry}, for example, in a CI/CD pipeline deployed in production. The Core Registry API v2 provides operations for artifacts, versions, metadata, and rules stored in {registry}. For detailed information, see the {registry-rest-api}. +Client applications can use {registry} REST API operations to manage schema and API artifacts in {registry}, for example, in a CI/CD pipeline deployed in production. The Core Registry API v3 provides operations for artifacts, versions, metadata, and rules stored in {registry}. For detailed information, see the {registry-rest-api}. -This chapter shows examples of how to use the Core Registry API v2 to perform the following tasks: +This chapter shows examples of how to use the Core Registry API v3 to perform the following tasks: -ifdef::rh-openshift-sr[] -* xref:creating-access-token-for-registry-rest-api_{context}[] -endif::[] * xref:managing-artifacts-using-rest-api_{context}[] * xref:managing-artifact-versions-using-rest-api_{context}[] * xref:managing-artifact-references-using-rest-api_{context}[] @@ -26,9 +23,6 @@ endif::[] * link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation] //INCLUDES -ifdef::rh-openshift-sr[] -include::{mod-loc}getting-started/proc-creating-access-token-rest-api.adoc[leveloffset=+1] -endif::[] include::{mod-loc}getting-started/proc-managing-artifacts-using-rest-api.adoc[leveloffset=+1] include::{mod-loc}getting-started/proc-managing-artifact-versions-using-rest-api.adoc[leveloffset=+1] include::{mod-loc}getting-started/proc-managing-artifact-references-using-rest-api.adoc[leveloffset=+1] diff --git a/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-ui.adoc b/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-ui.adoc index 12261b5dfe..7e6712d538 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-ui.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-ui.adoc @@ -14,7 +14,6 @@ endif::[] * xref:browsing-artifacts-using-console_{context}[] * xref:adding-artifacts-using-console_{context}[] * xref:configuring-rules-using-console_{context}[] -* xref:generating-client-sdk-using-web-console_{context}[] * xref:changing-artifact-owner-using-console_{context}[] * xref:configuring-settings-using-console_{context}[] * xref:exporting-importing-using-web-console_{context}[] @@ -27,7 +26,6 @@ endif::[] include::{mod-loc}getting-started/proc-browsing-artifacts-using-console.adoc[leveloffset=+1] include::{mod-loc}getting-started/proc-adding-artifacts-using-console.adoc[leveloffset=+1] include::{mod-loc}getting-started/proc-configuring-rules-using-console.adoc[leveloffset=+1] -include::{mod-loc}getting-started/proc-generating-client-sdk-using-web-console.adoc[leveloffset=+1] include::{mod-loc}getting-started/proc-changing-artifact-owner-using-console.adoc[leveloffset=+1] include::{mod-loc}getting-started/proc-configuring-settings-using-console.adoc[leveloffset=+1] include::{mod-loc}getting-started/proc-exporting-importing-using-web-console.adoc[leveloffset=+1] diff --git a/docs/modules/ROOT/pages/getting-started/assembly-migrating-registry-v1-v2.adoc b/docs/modules/ROOT/pages/getting-started/assembly-migrating-registry-v2-v3.adoc similarity index 92% rename from docs/modules/ROOT/pages/getting-started/assembly-migrating-registry-v1-v2.adoc rename to docs/modules/ROOT/pages/getting-started/assembly-migrating-registry-v2-v3.adoc index d9920fe70a..a3a3864197 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-migrating-registry-v1-v2.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-migrating-registry-v2-v3.adoc @@ -6,7 +6,7 @@ include::{mod-loc}shared/all-attributes.adoc[] = Migrating an existing {registry} deployment [role="_abstract"] -This chapter explains how to migrate an existing {registry} deployment from version {registry-v1} to version 2.x. +This chapter explains how to migrate an existing {registry} deployment from version 2.x to version 3.x. * xref:registry-migration_{context}[] * xref:migrating-registry-data_{context}[] diff --git a/docs/modules/ROOT/pages/getting-started/assembly-using-the-registry-client.adoc b/docs/modules/ROOT/pages/getting-started/assembly-using-the-registry-client.adoc index 5dfaa86042..87906c0d97 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-using-the-registry-client.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-using-the-registry-client.adoc @@ -1,17 +1,17 @@ // Metadata created by nebel include::{mod-loc}shared/all-attributes.adoc[] -[id="using-the-registry-client_{context}"] -= Managing {registry} content using a Java client +[id="using-the-registry-sdk_{context}"] += Managing {registry} content using a SDK [role="_abstract"] -You can write a {registry} Java client application and use it to manage artifacts stored in {registry}: +You can write a {registry} client application (in Java, Typescript, Python, or Golang) and use it to manage artifacts stored in {registry}: -* xref:registry-client-intro_{context}[] -* xref:writing-registry-client_{context}[] -* xref:registry-client-config_{context}[] +* xref:registry-sdk-intro_{context}[] +* xref:writing-registry-sdk_{context}[] +* xref:registry-sdk-config_{context}[] //INCLUDES -include::{mod-loc}getting-started/con-registry-client.adoc[leveloffset=+1] -include::{mod-loc}getting-started/proc-writing-registry-client.adoc[leveloffset=+1] -include::{mod-loc}getting-started/ref-registry-client.adoc[leveloffset=+1] +include::{mod-loc}getting-started/con-registry-sdk.adoc[leveloffset=+1] +include::{mod-loc}getting-started/proc-writing-registry-sdk.adoc[leveloffset=+1] +include::{mod-loc}getting-started/ref-registry-sdk.adoc[leveloffset=+1] diff --git a/docs/modules/ROOT/partials/getting-started/con-kafka-connect-converters.adoc b/docs/modules/ROOT/partials/getting-started/con-kafka-connect-converters.adoc index 7fe16464dc..4110ac037e 100644 --- a/docs/modules/ROOT/partials/getting-started/con-kafka-connect-converters.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-kafka-connect-converters.adoc @@ -7,12 +7,7 @@ You can use {registry} with Apache Kafka Connect to stream data between Kafka and external systems. Using Kafka Connect, you can define connectors for different systems to move large volumes of data into and out of Kafka-based systems. .{registry} and Kafka Connect architecture -ifdef::apicurio-registry,rh-service-registry[] image::images/getting-started/registry-connect-architecture.png[Registry and Kafka Connect architecture] -endif::[] -ifdef::rh-openshift-sr[] -image::../_images/introduction/registry-connect-architecture.png[Registry and Kafka Connect architecture] -endif::[] {registry} provides the following features for Kafka Connect: diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-artifacts.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-artifacts.adoc index 4b8f5c7d87..8e51d25a09 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-artifacts.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-artifacts.adoc @@ -28,6 +28,51 @@ The items stored in {registry}, such as event schemas and API designs, are known When a schema or API design is added as an artifact in {registry}, client applications can then use that schema or API design to validate that the client messages conform to the correct data structure at runtime. +Artifacts have metadata, both generated and editable. Standard metadata for an artifact includes (but may not be limited to): + +=== Generated or immutable properties + +- groupId +- artifactId +- artifactType +- createdOn +- modifiedBy +- modifiedOn + +=== Editable properties +- name +- description +- labels +- owner + +[discrete] +== Artifact Versions +Every artifact is composed of zero or more _artifact version_s. Only artifact versions have actual +content (as well as metadata). These versions represent the evolution of the content of an artifact, +and are immutable. You can think of an Artifact as an ordered sequence of Versions, typically with +the most recent version representing the "current" schema or API design content. + + +Artifact Versions have metadata, both generated and editable. Standard metadata for an artifact version includes (but may not be limited to): + +=== Generated or immutable properties + +- groupId +- artifactId +- version +- globalId +- contentId +- owner +- createdOn +- modifiedBy +- modifiedOn + +=== Editable properties +- name +- description +- labels +- state + [discrete] == Groups of schemas and APIs @@ -38,20 +83,23 @@ You can create optional artifact groups when adding your schemas and API designs Schema and API groups can contain multiple artifact types. For example, you could have Protobuf, Avro, JSON Schema, OpenAPI, or AsyncAPI artifacts all in the same group. -You can create schema and API artifacts and groups using the {registry} web console, REST API, command line, Maven plug-in, or Java client application. The following simple example shows using the Core Registry REST API: +Groups have metadata, both generated and editable. Standard metadata for a group includes (but may not be limited to): -[source,bash] ----- -$ 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"}]}' \ - https://my-registry.example.com/apis/registry/v2/groups/my-group/artifacts ----- +=== Generated or immutable properties + +- groupId +- owner +- createdOn +- modifiedBy +- modifiedOn + +=== Editable properties +- description +- labels -This example creates an artifact group named `my-group` and adds an Avro schema with an artifact ID of `share-price`. +You can create schema and API artifacts and groups using the {registry} web console, REST API, command line, Maven plug-in, or Java client application. -NOTE: Specifying a group is optional when using the {registry} web console, and a `default` group is created automatically. When using the REST API or Maven plug-in, specify the `default` group in the API path if you do not want to create a unique group. +NOTE: Specifying a group is optional when using the {registry} web console, and the `default` group is used automatically. When using the REST API or Maven plug-in, specify the `default` group in the API path if you do not want to create a unique group. [role="_additional-resources"] .Additional resources @@ -121,12 +169,6 @@ You can manage artifact references using the {registry} core REST API, Maven plu .Additional resources * For details on managing artifact references, see: -ifdef::apicurio-registry,rh-service-registry[] ** {managing-registry-artifacts-api}. ** {managing-registry-artifacts-maven}. -endif::[] -ifdef::rh-openshift-sr[] -** {base-url}{manage-api-url-registry}[Managing Service Registry data using the Core Registry API]. -** {base-url}{manage-maven-plugin-url-registry}[Managing schemas and APIs using the Service Registry Maven plug-in]. -endif::[] * For a Java example, see the https://github.com/Apicurio/apicurio-registry/tree/main/examples/serdes-with-references[Apicurio Registry SerDes with references demonstration]. diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-client.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-client.adoc deleted file mode 100644 index 4be2dac01a..0000000000 --- a/docs/modules/ROOT/partials/getting-started/con-registry-client.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Metadata created by nebel - -[id="registry-client-intro_{context}"] -= {registry} Java client - -[role="_abstract"] -You can manage artifacts stored in {registry} by using a Java client application. You can create, read, update, or delete artifacts by using the {registry} Java client classes. You can also use the {registry} Java client to perform administrator functions, such as managing global rules or importing and exporting {registry} data. - -You can access the {registry} Java client by adding the correct dependency to your Apache Maven project. -ifdef::apicurio-registry,rh-service-registry[] -For more details, see xref:writing-registry-client_registry[]. -endif::[] -ifdef::rh-openshift-sr[] -For more details, see xref:writing-registry-client_java-client[Writing {registry} Java client applications]. -endif::[] - -The {registry} client is implemented by using the HTTP client provided by the JDK, which you can customize as needed. For example, you can add custom headers or enable configuration options for Transport Layer Security (TLS) authentication. -ifdef::apicurio-registry,rh-service-registry[] -For more details, see xref:registry-client-config_registry[]. -endif::[] -ifdef::rh-openshift-sr[] -For more details, see xref:registry-client-config_java-client[{registry} Java client configuration]. -endif::[] diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-content.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-content.adoc index 0108a6bfb2..7373c3ae89 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-content.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-content.adoc @@ -4,29 +4,21 @@ = Manage {registry} content using client tools [role="_abstract"] -You can manage {registry} content using the {registry} web console, REST API, command line, Maven plug-in, or Java client. +You can manage {registry} content using the {registry} web console, REST API, command line, Maven plug-in, or client SDKs. == {registry} web console You can use the {registry} web console to browse and search the schema and API artifacts, groups, and versions stored in {registry}, and to add new schema and API artifacts, groups, and versions. You can also configure optional validation or compatibility rules for {registry} content, both globally and for each schema and API artifact. .{registry} web console -ifdef::apicurio-registry,rh-service-registry[] image::images/getting-started/registry-web-console.png[{registry} web console] -endif::[] -ifdef::rh-openshift-sr[] -image::../_images/introduction/registry-web-console.png[{registry} web console] -endif::[] == Core Registry API Using the Core Registry API, client applications can manage the schema and API artifacts in {registry}. This API provides create, read, update, and delete operations for artifacts, versions, metadata, and rules. It also provides search and admin operations, such as managing global rules or importing and exporting {registry} data. {registry} provides compatibility with other schema registry APIs, such as Confluent Schema Registry. -== OpenShift Application Services CLI -You can use the Red Hat OpenShift Application Services (`rhoas`) command line interface to create, read, and delete {registry} instances, and to manage schema and API artifacts stored in {registry}. The `rhoas` CLI provides create, read, update, and delete operations for {registry} artifacts, versions, and metadata. - -== {registry} Java client -You can use the {registry} Java client classes to create, read, update, or delete artifacts stored in {registry}. You can also perform admin functions using the Java client, such as managing global rules or importing and exporting {registry} data. +== {registry} SDKs +You can use the {registry} language SDKs to create, read, update, or delete artifacts stored in {registry}. You can also perform admin functions using the SDKs, such as managing global rules or importing and exporting {registry} data. == {registry} Maven plug-in You can use the {registry} Maven plug-in to add, download, or test {registry} artifacts in a Maven build. This includes adding artifacts during a build, or downloading artifacts when generating code from a schema. If content rules are configured, you can test that artifacts can be added before making changes. diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-distros.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-distros.adoc index f00bf509a5..002aa600d7 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-distros.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-distros.adoc @@ -4,28 +4,26 @@ = {registry} available distributions [role="_abstract"] -{registry} provides the following distribution options. +{registry} provides the following components as part of its distribution. ifdef::apicurio-registry[] .{registry} images [%header,cols="2,4"] |=== -|Distribution option +|Component |Container Image -|In-memory -|https://hub.docker.com/r/apicurio/apicurio-registry-mem -|PostgreSQL database -|https://hub.docker.com/r/apicurio/apicurio-registry-sql -|Apache Kafka -|https://hub.docker.com/r/apicurio/apicurio-registry-kafkasql -|{registry} Operator +|Back-end +|https://hub.docker.com/r/apicurio/apicurio-registry +|User Interface +|https://hub.docker.com/r/apicurio/apicurio-registry-ui +|{registry} Operator |https://hub.docker.com/r/apicurio/apicurio-registry-operator |=== .Additional resources -* For details on building from source code and running Docker images, see https://github.com/Apicurio/apicurio-registry -* For details on using the Operator to deploy, see https://github.com/Apicurio/apicurio-registry-operator +* For details on building from source code and running Docker images, see link:https://github.com/Apicurio/apicurio-registry[] +* For details on using the Operator to deploy, see link:https://github.com/Apicurio/apicurio-registry/tree/main/operator[] endif::[] @@ -43,10 +41,10 @@ ifdef::rh-service-registry[] |Container image for {registry} Operator |link:{download-url-registry-container-catalog}[{org-name} Ecosystem Catalog] |General Availability -|Container image for Kafka storage in AMQ Streams +|Container image for Apicurio Registry (Back End) |link:{download-url-registry-container-catalog}[{org-name} Ecosystem Catalog] |General Availability -|Container image for database storage in PostgreSQL +|Container image for Apicurio Registry (User Interface) |link:{download-url-registry-container-catalog}[{org-name} Ecosystem Catalog] |General Availability |=== @@ -61,9 +59,6 @@ ifdef::rh-service-registry[] |Example custom resource definitions for installation |link:{download-url-registry-distribution}[{org-name} Software Downloads] |General Availability -|{registry} v1 to v2 migration tool -|link:{download-url-registry-distribution}[{org-name} Software Downloads] -|General Availability |Maven repository |link:{download-url-registry-distribution}[{org-name} Software Downloads] |General Availability diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-migration.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-migration.adoc index 2318ef0892..cc18f69480 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-migration.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-migration.adoc @@ -1,22 +1,25 @@ // Metadata created by nebel [id="registry-migration_{context}"] -= Migration from {registry} {registry-v1} to 2.x += Migration from {registry} 2.x to 3.x [role="_abstract"] -{registry} 2.x includes new features with breaking changes from the previous {registry} {registry-v1} release. This section describes the major changes between {registry} {registry-v1} and version 2.x. +{registry} 3.x includes new features with breaking changes from the previous {registry} 2.x release. This section describes the major changes between {registry} 2.x and version 3.x, along with the best approach to migrating. -Because of the breaking changes in 2.x, there is no automatic upgrade and a migration process is required. This involves moving the data in your existing registry to a new registry. You must also review your existing registry client applications and update their configuration to meet the new requirements. +Because of the breaking changes in 3.x, there is no automatic upgrade and a migration process is required. This involves exporting the data in your existing registry to a new registry. You must also review your existing registry client applications and update their configurations to meet the new requirements. -When migrating to version 2.x, you must take the following major changes into account: +When migrating to version 3.x, you must take the following major changes into account: + +== Data storage changes +All of the storage options from 2.x continue to be supported in 3.x, but any data currently in either the Kafka topic +or in the database is no longer compatible with 3.x. This means that, in order to migrate from 2.x to 3.x, you will +need to use the Export feature of {registry} to create a .ZIP file containing all of your 2.x data. -== New data storage options -The existing registry data storage options in {registry} {registry-v1} (`streams`,`jpa`, and `infinispan`) have been replaced with new storage options in version 2.x (`sql` and `kafkasql`). These new storage options provide more robust, performant, and maintainable {registry} deployments. ifdef::apicurio-registry[] -The in-memory storage option (`mem`) is also still available, but is not suitable for production workloads. +The in-memory storage option is also still available, but is not suitable for production workloads. endif::[] -For details on how to deploy {registry} 2.x with your chosen storage option, +For details on how to deploy {registry} 3.x with your chosen storage option, ifdef::apicurio-registry[] see {installing-the-registry-storage-openshift}. endif::[] @@ -24,15 +27,20 @@ ifdef::rh-service-registry[] see link:{LinkServiceRegistryInstall}[{NameServiceRegistryInstall}]. endif::[] -== New v2 REST API -{registry} 2.x includes a new REST API with support for artifact groups and improved long term maintainability. {registry} still supports the version 2 of the core REST API as well as various compatibility APIs, for example, the Confluent schema registry API. +== New v3 REST API +{registry} 3.x includes a new REST API with support for empty artifacts, artifact branches, group level rules, new search capabilities, and much more. {registry} still supports version 2.x of the core REST API as well as various compatibility APIs, for example, the Confluent schema registry API v7. However, version 2 of the Core REST API is now deprecated. + +== All new SDKs replace the Java client +* The {registry} Java client classes are no longer available in version 3.x and have been replaced by a new SDK generated using Kiota. -== Refactored Java client libraries -* The {registry} Java client classes are available in version 2.x in a different Maven module named `apicurio-registry-client`. +* In addition to Java, SDKs are now provided for Typescript, Python, and Golang. -* The Kafka client serializer and deserializer (SerDes) classes are available in version 2.x in three different Maven modules, one for each supported data format: Apache Avro, Protobuf, and JSON Schema. You can now use only the module you want without pulling in transitive dependencies that you are not concerned with. +* The Kafka client serializer and deserializer (SerDes) classes are available in version 3.x.... +== Deployment configuration has changed +{registry} 3.x has changed a number of configuration options and added some new ones. Options you may be using when deploying +2.x are likely still available, but may have been renamed. [role="_additional-resources"] .Additional resources -* For more details on the v2 REST API, see the link:{attachmentsdir}/registry-rest-api.htm[Registry REST API documentation]. +* For more details on the v3 REST API, see the link:{attachmentsdir}/registry-rest-api.htm[Registry REST API documentation]. diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-overview.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-overview.adoc index e5c0e83c32..3ca7147ec3 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-overview.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-overview.adoc @@ -6,7 +6,7 @@ [role="_abstract"] {registry} is a datastore for sharing standard event schemas and API designs across event-driven and API 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. -Client applications can dynamically push or pull the latest schema updates to or from {registry} at runtime without needing to redeploy. Developer teams can query {registry} for existing schemas required for services already deployed in production, and can register new schemas required for new services in development. +Client applications can dynamically push or pull the latest schema updates to or from {registry} at runtime without needing to redeploy. Developer teams can query {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 application code. {registry} can store schemas used to serialize and deserialize messages, which are referenced from your client applications to ensure that the messages that they send and receive are compatible with those schemas. @@ -15,30 +15,24 @@ Using {registry} to decouple your data structure from your applications reduces You can configure optional rules to govern the evolution of your {registry} content. These include rules to ensure that uploaded content is valid, or is compatible with other versions. Any configured rules must pass before new versions can be uploaded to {registry}, which ensures that time is not wasted on invalid or incompatible schemas or API designs. ifndef::apicurio-registry[] -{registry} is based on the Apicurio Registry open source community project. For details, see https://github.com/apicurio/apicurio-registry. +{registry} is based on the Apicurio Registry open source community project. For details, see link:https://www.apicur.io/registry/[]. endif::[] [discrete] == {registry} capabilities -ifdef::rh-openshift-sr[] -* Deployed as an easy-to-use managed cloud service without having to install, configure, or run your own {registry} instances. - -* Full integration with Red Hat OpenShift Streams for Apache Kafka managed cloud service, including Kafka topic-to-schema mapping. -endif::[] - * Multiple payload formats for standard event schema and API specifications such as Apache Avro, JSON Schema, Google Protobuf, AsyncAPI, OpenAPI, and more. ifdef::rh-service-registry[] -* Pluggable {registry} storage options in AMQ Streams or PostgreSQL database. +* Pluggable {registry} storage options for storing content in AMQ Streams or PostgreSQL database. endif::[] ifdef::apicurio-registry[] -* Pluggable {registry} storage options in Apache Kafka or PostgreSQL database. +* Pluggable {registry} storage options for storing content in Apache Kafka or PostgreSQL database. endif::[] * Rules for content validation, compatibility, and integrity to govern how {registry} content evolves over time. -* {registry} content management using web console, REST API, command line, Maven plug-in, or Java client. +* {registry} content management using web console, REST API, command line, Maven plug-in, or language SDKs. * Full Apache Kafka schema registry support, including integration with Kafka Connect for external systems. @@ -46,10 +40,8 @@ endif::[] * Compatibility with existing Confluent schema registry client applications. -ifdef::apicurio-registry,rh-service-registry[] * Cloud-native Quarkus Java runtime for low memory footprint and fast deployment times. -* Operator-based installation of {registry} on OpenShift. +* Operator-based installation of {registry} on OpenShift/Kubernetes. * OpenID Connect (OIDC) authentication using {keycloak}. -endif::[] diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-rest-api.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-rest-api.adoc index 0044a0cc68..fe03a22bb9 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-rest-api.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-rest-api.adoc @@ -4,24 +4,28 @@ [role="_abstract"] = {registry} REST API for clients -Client applications can use the Core Registry API v2 to manage the schema and API artifacts in {registry}. This API provides operations for the following features: +Client applications can use the Core Registry API v3 to manage the schema and API artifacts in {registry}. This API provides operations for the following features: Admin:: -Export or import {registry} data in a `.zip` file, and manage logging levels for the {registry} instance at runtime. +Export or import {registry} data in a `.zip` file, and manage logging levels for the {registry} at runtime. +Groups:: +Manage groups of artifacts in {registry}. You can create groups to better organize your artifacts. +Group Rules:: +Configure rules to govern the content evolution of schemas or API artifacts within a specific group to prevent invalid or incompatible content from being added to {registry}. Group rules override any global rules configured. Artifacts:: -Manage schema and API artifacts stored in {registry}. You can also manage the lifecycle state of an artifact: enabled, disabled, or deprecated. +Manage schema and API artifacts stored in {registry}. Artifact metadata:: Manage details about a schema or API artifact. You can edit details such as artifact name, description, or labels. Details such as 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 {registry}. Artifact rules override any global rules configured. +Configure rules to govern the content evolution of a specific schema or API artifact to prevent invalid or incompatible content from being added to {registry}. Artifact rules override any group and/or global rules configured. 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. +Manage the sequence of versions that make up the content of a schema or API artifact. You can also manage the lifecycle state of an artifact version: enabled, disabled, or deprecated. 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 {registry}. Global rules are applied only if an artifact does not have its own specific artifact rules configured. +Configure rules to govern the content evolution of all schema and API artifacts to prevent invalid or incompatible content from being added to {registry}. Global rules are applied only if an artifact and its group do not have rules configured. Search:: Browse or search for schema and API artifacts and versions, for example, by name, group, description, or label. System:: -Get the {registry} version and the limits on resources for the {registry} instance. +Get the {registry} version and the limits on resources for the {registry} server. Users:: Get the current {registry} user. @@ -39,7 +43,5 @@ endif::[] [role="_additional-resources"] .Additional resources -* For more information on the Core Registry API v2, see the {registry-rest-api}. -ifdef::apicurio-registry,rh-service-registry[] -* For API documentation on the Core Registry API v2 and all compatible APIs, browse to the `/apis` endpoint of your {registry} instance, for example, `\http://MY-REGISTRY-URL/apis`. -endif::[] +* For more information on the Core Registry API v3, see the {registry-rest-api}. +* For API documentation on the Core Registry API v3 and all compatible APIs, browse to the `/apis` endpoint of your {registry}, for example, `\http://MY-REGISTRY-URL/apis`. diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-rules.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-rules.adoc index b18f827ce5..f777c2b522 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-rules.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-rules.adoc @@ -5,23 +5,22 @@ = Govern {registry} content using rules [role="_abstract"] -To govern the evolution of artifact content added to {registry}, you can configure optional rules. All configured global rules or artifact-specific rules must pass before a new artifact version can be uploaded to {registry}. Configured artifact-specific rules override any configured global rules. +To govern the evolution of artifact content added to {registry}, you can configure optional rules. All configured global rules, group-specific rules, or artifact-specific rules must pass before a new artifact version can be added to {registry}. Configured artifact-specific rules override any configured group-specific rules, which in turn override any configured global rules. -The goal of these rules is to prevent invalid content from being added to {registry}. For example, content can be invalid for the following reasons: +The goal of these rules is to prevent invalid content from being added to {registry} and to control the evolution of an artifact (by e.g. checking the compatibility of a new artifact version against previous versions). For example, content can be invalid for the following reasons: * Invalid syntax for a given artifact type, for example, `AVRO` or `PROTOBUF`. * Valid syntax, but semantics violate a specification. * Incompatibility, when new content includes breaking changes relative to the current artifact version. * Artifact reference integrity, for example, a duplicate or non-existent artifact reference mapping. -You can enable optional content rules using the {registry} web console, REST API commands, or a Java client application. +You can enable optional content rules using the {registry} web console, REST API commands, or by using one of the SDKs. [id="registry-rules-apply_{context}"] == When rules are applied Rules are applied only when content is added to {registry}. This includes the following REST operations: * Adding an artifact -* Updating an artifact * Adding an artifact version If a rule is violated, {registry} returns an HTTP error. The response body includes the violated rule and a message showing what went wrong. @@ -30,34 +29,31 @@ If a rule is violated, {registry} returns an HTTP error. The response body inclu == Order of precedence of rules The order of precedence for artifact-specific and global rules is as follows: -* If you enable an artifact-specific rule, and the equivalent global rule is enabled, the artifact rule overrides the global rule. +* Artifact-specific rules have the highest priority +* Group-specific rules have the next highest priority +* Global rules have the lowest priority -* If you disable an artifact-specific rule, and the equivalent global rule is enabled, the global rule applies. - -* If you disable an artifact-specific rule, and the equivalent global rule is disabled, the rule is disabled for all artifacts. - -* If you set a rule value to `NONE` at the artifact level, you override the enabled global rule. In this case, the artifact rule value of `NONE` takes precedence for this artifact, but the enabled global rule continues to apply to any other artifacts that have the rule disabled at the artifact level. +NOTE: If a rule is configured at a higher level (e.g. at the global level), but you want that rule to be disabled at a lower level, you must configure the same rule (so that it overrides it) at the lower level and set its rules value to `NONE`. [id="registry-rules-work_{context}"] == How rules work -Each rule has a name and configuration information. {registry} maintains the list of rules for each artifact and the list of global rules. Each rule in the list consists of a name and configuration for the rule implementation. +Each rule has a name and configuration information. {registry} maintains the list of rules for each artifact, each group, and the list of global rules. Each rule in the list consists of a name and configuration for the rule implementation. -A rule is provided with the content of the current version of the artifact (if one exists) and the new version of the artifact being added. The rule implementation returns true or false depending on whether the artifact passes the rule. If not, {registry} reports the reason why in an HTTP error response. Some rules might not use the previous version of the content. For example, compatibility rules use previous versions, but syntax or semantic validity rules do not. +When a rule is executed, it is provided with the content of the current version of the artifact (if one exists) and the new version of the artifact being added. The rule implementation returns either passes or fails depending on whether the artifact passes the rule. If not, {registry} reports the reason why in an HTTP error response. Some rules might not use the previous version of the content. For example, compatibility rules use previous versions, but syntax or semantic validity rules do not. [role="_additional-resources"] .Additional resources For more details, see {registry-rule-reference}. -ifdef::apicurio-registry,rh-service-registry[] [id="registry-rules-config_{context}"] == Content rule configuration -Administrators can configure {registry} global rules and artifact-specific rules. Developers can configure artifact-specific rules only. +Administrators can configure {registry} global rules, group-specific rules, and artifact-specific rules. Developers can configure group-specific and artifact-specific rules only. -{registry} applies the rules configured for the specific artifact. If no rules are configured at that level, {registry} applies the globally configured rules. If no global rules are configured, no rules are applied. +{registry} applies the rules configured for the specific artifact. If no rules are configured at that level, {registry} applies the group-specific rules. If no rules are configured at the group level, then {registry} applies the globally configured rules. If no global rules are configured, then no rules are applied. [discrete] -=== Configure artifact rules -You can configure artifact rules using the {registry} web console or REST API. For details, see the following: +=== Configure group and artifact specific rules +You can configure group-specific and artifact-specific rules using the {registry} web console or REST API. For details, see the following: * {managing-registry-artifacts-ui} * link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation] @@ -73,7 +69,7 @@ Administrators can configure global rules in several ways: .Configure default global rules Administrators can configure {registry} at the application level to enable or disable global rules. You can configure default global rules at installation time without post-install configuration using the following application property format: ---- -registry.rules.global. +apicurio.rules.global. ---- The following rule names are currently supported: @@ -88,4 +84,3 @@ configured. NOTE: You can configure these application properties as Java system properties or include them in the Quarkus `application.properties` file. For more details, see the https://quarkus.io/guides/config#overriding-properties-at-runtime[Quarkus documentation]. -endif::[] diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-sdk.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-sdk.adoc new file mode 100644 index 0000000000..dec608ddca --- /dev/null +++ b/docs/modules/ROOT/partials/getting-started/con-registry-sdk.adoc @@ -0,0 +1,39 @@ +// Metadata created by nebel + +[id="registry-sdk-intro_{context}"] += {registry} SDK + +[role="_abstract"] +You can manage artifacts stored in {registry} by using one of the provided SDKs. You can perform any desired operation supported by the REST API, including create, read, update, or delete of artifacts. You can even use the {registry} SDKs to perform administrator functions, such as managing global rules or importing and exporting {registry} data. + +You can use any of the following SDKs provided as part of {registry}: + +- Java +- Typescript +- Python +- Golang + +=== Java +You can access the {registry} Java SDK by adding the correct dependency to your Apache Maven project. +For more details, see xref:writing-registry-sdk_registry[]. + +The {registry} client is implemented by using the HTTP client provided by the JDK, which you can customize as needed. For example, you can add custom headers or enable configuration options for Transport Layer Security (TLS) authentication. +For more details, see xref:registry-sdk-config_registry[]. + +=== Typescript +You can access the {registry} Typescript SDK by adding the correct dependency to your application's `package.json` +file (assumes a node.js application): + +https://www.npmjs.com/package/@apicurio/apicurio-registry-sdk + +=== Python +You can access the {registry} Python SDK by adding the correct dependency to your python project (assumes you +are using pypi): + +https://pypi.org/project/apicurioregistrysdk/ + +=== Golang +You can access the {registry} Golang SDK by adding the correct dependency to your project: + +https://github.com/Apicurio/apicurio-registry/tree/main/go-sdk + diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-serde.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-serde.adoc index 7f8b0483ef..d9197d5059 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-serde.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-serde.adoc @@ -8,12 +8,7 @@ Kafka producer applications can use serializers to encode messages that conform to a specific event schema. Kafka consumer applications can then use deserializers to validate that messages have been serialized using the correct schema, based on a specific schema ID. .{registry} and Kafka client SerDes architecture -ifdef::apicurio-registry,rh-service-registry[] image::images/getting-started/registry-serdes-architecture.png[Kafka client SerDes architecture] -endif::[] -ifdef::rh-openshift-sr[] -image::../_images/introduction/registry-serdes-architecture.png[Kafka client SerDes architecture] -endif::[] {registry} provides Kafka client serializers/deserializers (SerDes) to validate the following message types at runtime: @@ -21,13 +16,7 @@ endif::[] * Google Protobuf * JSON Schema -ifdef::apicurio-registry,rh-service-registry[] -The {registry} Maven repository and source code distributions include -endif::[] -ifdef::rh-openshift-sr[] -The {registry} Maven repository includes -endif::[] -the Kafka SerDes implementations for these message types, which Kafka client application developers can use to integrate with {registry}. +The {registry} Maven repository and source code distributions include the Kafka SerDes implementations for these message types, which Kafka client application developers can use to integrate with {registry}. These implementations include custom Java classes for each supported message type, for example, `io.apicurio.registry.serde.avro`, which client applications can use to pull schemas from {registry} at runtime for validation. diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-serdes-concepts.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-serdes-concepts.adoc index 7ed739889c..5c094b123b 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-serdes-concepts.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-serdes-concepts.adoc @@ -53,22 +53,31 @@ To enable a consumer to use {registry} for deserialization: ** {registry} deserializer to use with the messages ** Input data stream for deserialization -.Retrieve schemas using a global ID -By default, the schema is retrieved from {registry} by the deserializer using a global ID, which is specified in the message being consumed. The schema global ID can be located in the message headers or in the message payload, depending on the configuration of the producer application. +.Retrieve schemas using a content ID +By default, the schema is retrieved from {registry} by the deserializer using a content ID (which is an ID unique to the *content* of an artifact version, but not unique to the version itself), which is specified in the message being consumed. The schema content ID can be located in the message headers or in the message payload, depending on the configuration of the producer application. By default, the content ID will be located in the message body. -When locating the global ID in the message payload, the format of the data begins with a magic byte, used as a signal to consumers, followed by the global ID, and the message data as normal. For example: +When locating the content ID in the message payload, the format of the data begins with a magic byte, used as a signal to consumers, followed by the content ID, and the message data as normal. For example: [source,shell,subs="+quotes,attributes"] ---- # ... [MAGIC_BYTE] -[GLOBAL_ID] +[CONTENT_ID] [MESSAGE DATA] ---- Then when you start Kafka and {registry}, you can access the schema to format messages received from the Kafka broker topic. -.Retrieve schemas using a content ID -Alternatively, you can configure to retrieve schemas from {registry} based on the content ID, which is the unique ID of the artifact content. While the global ID is the unique ID of an artifact version. +.Retrieve schemas using a global ID +Alternatively, you can configure to retrieve schemas from {registry} based on the global ID, which is the unique ID of the artifact version. The same options are available to you when using global ID instead of contentID. You can either send the global ID in the message headers or the message body (default). + +When locating the global ID in the message payload, the format of the data begins with a magic byte, used as a signal to consumers, followed by the global ID, and the message data as normal. For example: + +[source,shell,subs="+quotes,attributes"] +---- +# ... +[MAGIC_BYTE] +[GLOBAL_ID] +[MESSAGE DATA] +---- -The content ID does not uniquely identify a version, but uniquely identifies the version content only. If multiple versions share the exact same content, they have a different global ID but the same content ID. Confluent Schema Registry uses content ID by default. diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-serdes-constants.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-serdes-constants.adoc index 525ca485f8..6367fd7ba2 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-serdes-constants.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-serdes-constants.adoc @@ -5,7 +5,7 @@ = {registry} serializer/deserializer configuration in client applications [role="_abstract"] -You can configure specific client serializer/deserializer (SerDes) services and schema lookup strategies directly in a client application using the example constants shown in this section. Alternatively, you can configure the corresponding {registry} application properties in a file or an instance. +You can configure specific client serializer/deserializer (SerDes) services and schema lookup strategies directly in a client application using the example constants shown in this section. The following sections show examples of commonly used SerDes constants and configuration options. diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-serdes-protobuf.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-serdes-protobuf.adoc index ee284ef9af..307cafb1d0 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-serdes-protobuf.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-serdes-protobuf.adoc @@ -49,8 +49,7 @@ The deserializer class can determine the values for these options from the messa The ID location is determined by checking for the magic byte at the start of the message payload. If that byte is found, the ID is read from the message payload using the configured handler. If the magic byte is not found, the ID is read from the message headers. -NOTE: The Protobuf deserializer does not deserialize to your exact Protobuf Message implementation, -but rather to a `DynamicMessage` instance. There is no appropriate API to do otherwise. +NOTE: The Protobuf deserializer does not deserialize to your exact Protobuf Message implementation, but rather to a `DynamicMessage` instance. There is no appropriate API to do otherwise. .Protobuf SerDes and artifact references When a complex Protobuf message with an `import` statement is used, the imported Protobuf messages are stored in {registry} as separate artifacts. Then when {registry} gets the main schema to check a Protobuf message, the referenced schemes are also retrieved so the full message schema can be checked and serialized. diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-web-console.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-web-console.adoc index 59bb840420..a63e7e12cc 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-web-console.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-web-console.adoc @@ -6,24 +6,15 @@ [role="_abstract"] You can use the {registry} web console to browse and search the schema and API artifacts and optional groups stored in the registry, and to add new schema and API artifacts, groups, and versions. You can search for artifacts by label, name, group, and description. You can view an artifact’s content or its available versions, or download an artifact file locally. -You can also configure optional rules for registry content, both globally and for each schema and API artifact. These optional rules for content validation and compatibility are applied when new schema and API artifacts or versions are uploaded to the registry. +You can also configure optional rules for registry content, globally, for groups, and for each schema and API artifact. These optional rules for content validation and compatibility are applied when new schema and API artifacts or versions are uploaded to the registry. -ifdef::apicurio-registry,rh-service-registry[] For more details, see {registry-rule-reference}. -endif::[] .{registry} web console -ifdef::apicurio-registry,rh-service-registry[] image::images/getting-started/registry-web-console.png[{registry} web console] -endif::[] -ifdef::rh-openshift-sr[] -image::../_images/introduction/registry-web-console.png[{registry} web console] -endif::[] The {registry} web console is available from `{registry-url}`. -ifdef::apicurio-registry,rh-service-registry[] [role="_additional-resources"] .Additional resources * {managing-registry-artifacts-ui} -endif::[] diff --git a/docs/modules/ROOT/partials/getting-started/proc-adding-artifact-references-automatically-using-maven-plugin.adoc b/docs/modules/ROOT/partials/getting-started/proc-adding-artifact-references-automatically-using-maven-plugin.adoc index e8c13955ba..70767fb11d 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-adding-artifact-references-automatically-using-maven-plugin.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-adding-artifact-references-automatically-using-maven-plugin.adoc @@ -79,7 +79,7 @@ This section shows a simple example of using the Maven plug-in to register an Av register <1> - MY-REGISTRY-URL/apis/registry/v2 <2> + MY-REGISTRY-URL/apis/registry/v3 <2> MY-AUTH-SERVER MY-CLIENT-ID MY-CLIENT-SECRET <3> @@ -105,13 +105,8 @@ This section shows a simple example of using the Maven plug-in to register an Av ---- + <1> Specify `register` as the execution goal to upload the schema artifacts to {registry}. -<2> Specify the {registry} URL by using the `../apis/registry/v2` endpoint. -ifdef::apicurio-registry,rh-service-registry[] +<2> Specify the {registry} URL by using the `../apis/registry/v3` endpoint. <3> If authentication is required, you can specify your authentication server and client credentials. -endif::[] -ifdef::rh-openshift-sr[] -<3> Specify your service account ID and secret and the {org-name} Single Sign-On authentication server: `{sso-token-url}` -endif::[] <4> Specify the parent artifact group ID that contains the references. You can specify the `default` group if you do not want to use a unique group ID. <5> Specify the location of the parent artifact file. All referenced artifacts must also be located in the same directory. <6> Set the `` option to true to automatically detect and register all references to artifacts in the same directory. You can register multiple artifact references in this way. diff --git a/docs/modules/ROOT/partials/getting-started/proc-adding-artifact-references-manually-using-maven-plugin.adoc b/docs/modules/ROOT/partials/getting-started/proc-adding-artifact-references-manually-using-maven-plugin.adoc index 7ccaabb9b2..4ba2078d50 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-adding-artifact-references-manually-using-maven-plugin.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-adding-artifact-references-manually-using-maven-plugin.adoc @@ -70,7 +70,7 @@ This example then creates a `TradeKey` schema artifact, which includes a referen register <1> - MY-REGISTRY-URL/apis/registry/v2 <2> + MY-REGISTRY-URL/apis/registry/v3 <2> MY-AUTH-SERVER MY-CLIENT-ID MY-CLIENT-SECRET <3> @@ -109,13 +109,8 @@ This example then creates a `TradeKey` schema artifact, which includes a referen ---- + <1> Specify `register` as the execution goal to upload the schema artifacts to {registry}. -<2> Specify the {registry} URL by using the `../apis/registry/v2` endpoint. -ifdef::apicurio-registry,rh-service-registry[] +<2> Specify the {registry} URL by using the `../apis/registry/v3` endpoint. <3> If authentication is required, you can specify your authentication server and client credentials. -endif::[] -ifdef::rh-openshift-sr[] -<3> Specify your service account ID and secret and the {org-name} Single Sign-On authentication server: `{sso-token-url}` -endif::[] <4> Specify the {registry} artifact group ID. You can specify the `default` group if you do not want to use a unique group ID. <5> Specify the {registry} artifact reference using its group ID, artifact ID, version, type, and location. You can register multiple artifact references in this way. diff --git a/docs/modules/ROOT/partials/getting-started/proc-adding-artifacts-using-console.adoc b/docs/modules/ROOT/partials/getting-started/proc-adding-artifacts-using-console.adoc index 57c5199af2..93ebfe9ae7 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-adding-artifacts-using-console.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-adding-artifacts-using-console.adoc @@ -5,74 +5,67 @@ = Adding artifacts using the {registry} web console [role="_abstract"] -You can use the {registry} web console to upload schema and API artifacts to {registry}. This section shows simple examples of uploading {registry} artifacts and adding new artifact versions. - -ifdef::rh-openshift-sr[] -NOTE: When uploading an artifact from a URL, you must specify an HTTPS URL. HTTP URLs are not supported. -endif::[] +You can use the {registry} web console to upload schema and API artifacts to {registry}. This section shows simple examples of creating {registry} artifacts and adding new artifact versions. .Prerequisites -ifdef::apicurio-registry,rh-service-registry[] * {registry} is installed and running in your environment. -endif::[] * You are logged in to the {registry} web console: + `{registry-url}` -ifdef::rh-openshift-sr[] -* You have access to a running {registry} instance. -endif::[] .Procedure -ifdef::rh-openshift-sr[] -. In the {registry} web console, click your existing {registry} instance, or click *Create {registry} instance* to provision a new one. -endif::[] -. On the *Artifacts* tab, click *Upload artifact*, and specify the following details: -** *Group & ID*: Use the default empty settings to automatically generate an artifact ID and add the artifact to the `default` artifact group. Alternatively, you can enter an optional artifact group name or ID. -** *Type*: Use the default *Auto-Detect* setting to automatically detect the artifact type, or select the artifact type from the list, for example, *Avro Schema* or *OpenAPI*. You must manually select the *Kafka Connect Schema* artifact type, which cannot be automatically detected. +. On the *Explore* tab, click *Create artifact*, and specify the following details: +** *Artifact Coordinates* / *Group ID & Artifact ID*: Use the default empty settings to automatically generate an artifact ID and add the artifact to the `default` artifact group. Alternatively, you can enter an optional artifact group or artifact ID. +** *Artifact Coordinates* / *Type*: Use the default *Auto-Detect* setting to automatically detect the artifact type (not allowed if creating an empty artifact), or select the artifact type from the list, for example, *Avro Schema* or *OpenAPI*. You must manually select the *Kafka Connect Schema* artifact type, which cannot be automatically detected. ++ +** *Artifact Metadata* / *Name*: Enter an optional friendly name for the new artifact. +** *Artifact Metadata* / *Description*: Enter an optional description for the new artifact. +** *Artifact Metadata* / *Labels*: Optionally add one or more label (name/value pair) for the new artifact. + -** *Artifact*: Specify the artifact location using either of the following options: +** *Version Content* / *Version Number*: Optionally add a version string if creating a first version. +** *Version Content* / *Content*: Specify the content using either of the following options: *** *From file*: Click *Browse*, and select a file, or drag and drop a file. For example, `my-openapi.json` or `my-schema.proto`. Alternatively, you can enter the file contents in the text box. *** *From URL*: Enter a valid and accessible URL, and click *Fetch*. For example: `\https://petstore3.swagger.io/api/v3/openapi.json`. ++ +** *Version Metadata* / *Name*: Enter an optional friendly name for the first artifact version. +** *Version Metadata* / *Description*: Enter an optional description for the first artifact version. +** *Version Metadata* / *Labels*: Optionally add one or more label (name/value pair) for the first artifact version. -. Click *Upload* and view the artifact details: +. Click *Create* and view the artifact details: + -** *Overview*: Displays artifact version metadata such as artifact name, artifact ID, global ID, content ID, labels, properties, and so on. Also displays rules for validity and compatibility that you can configure for artifact content. -** *Documentation* (OpenAPI and AsyncAPI only): Displays automatically-generated REST API documentation. -** *Content*: Displays a read-only view of the full artifact content. For JSON content, you can click *JSON* or *YAML* to display your preferred format. -** *References*: Displays a read-only view of all artifacts referenced by this artifact. You can also click *View artifacts that reference this artifact*. You can add artifact references using the {registry} Maven plug-in or REST API only. +** *Overview*: Displays artifact metadata such as artifact ID, name, description, labels, and so on. Also displays rules for validity and compatibility that you can configure for artifact content. +** *Versions*: Displays a list of all artifact versions. This will be empty unless you chose to upload a first version when you created the artifact. +** *Branches*: Displays a list of branches for the artifact. This will display at least the `latest` branch, but might display other generated branches depending on your configuration. + -The following example shows an example OpenAPI artifact: +The following example shows an example Apache Avro artifact: + .Artifact details in {registry} web console -ifdef::apicurio-registry,rh-service-registry[] image::images/getting-started/registry-web-console-artifact.png[Artifact details in Registry web console] -endif::[] -ifdef::rh-openshift-sr[] -image::../_images/user-guide/registry-web-console-artifact.png[Artifact details in Registry web console] -endif::[] . On the *Overview* tab, click the *Edit* pencil icon to edit artifact metadata such as name or description. + -You can also enter an optional comma-separated list of labels for searching, or add key-value pairs of arbitrary properties associated with the artifact. To add properties, perform the following steps: +You can also add zero or more labels (name + value) for categorizing and searching purposes. To add labels, perform the following steps: + -.. Click *Add property*. -.. Enter the key name and the value. +.. Click *Add label*. +.. Enter the key name and the value (optional). .. Repeat the first two steps to add multiple properties. .. Click *Save*. . To save the artifact contents to a local file, for example, `my-protobuf-schema.proto` or `my-openapi.json`, click *Download* at the end of the page. -. To add a new artifact version, click *Upload new version* in the page header, and drag and drop or click *Browse* to upload the file, for example, `my-avro-schema.json` or `my-openapi.json`. - +. To add a new artifact version, switch to the **Versions** tab and then click *Create version* in the toolbar. From there, provide the following information: +.. *Version Number*: Optionally add a version string for the new version. +.. *Content*: Specify the content using either of the following options: +... *From file*: Click *Browse*, and select a file, or drag and drop a file. For example, `my-openapi.json` or `my-schema.proto`. Alternatively, you can enter the file contents in the text box. +... *From URL*: Enter a valid and accessible URL, and click *Fetch*. For example: `\https://petstore3.swagger.io/api/v3/openapi.json`. +.. Now you can click the *Create* button to create the new version. . To delete an artifact, click *Delete* in the page header. + WARNING: Deleting an artifact deletes the artifact and all of its versions, and cannot be undone. -ifdef::apicurio-registry,rh-service-registry[] [role="_additional-resources"] .Additional resources * xref:browsing-artifacts-using-console_{context}[] * xref:configuring-rules-using-console_{context}[] * {registry-rule-reference} -endif::[] diff --git a/docs/modules/ROOT/partials/getting-started/proc-adding-artifacts-using-maven-plugin.adoc b/docs/modules/ROOT/partials/getting-started/proc-adding-artifacts-using-maven-plugin.adoc index 61c55c237f..71ae02ecfd 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-adding-artifacts-using-maven-plugin.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-adding-artifacts-using-maven-plugin.adoc @@ -26,7 +26,7 @@ The most common use case for the Maven plug-in is adding artifacts during a buil register <1> - MY-REGISTRY-URL/apis/registry/v2 <2> + MY-REGISTRY-URL/apis/registry/v3 <2> MY-AUTH-SERVER MY-CLIENT-ID MY-CLIENT-SECRET <3> @@ -54,13 +54,8 @@ The most common use case for the Maven plug-in is adding artifacts during a buil ---- + <1> Specify `register` as the execution goal to upload the schema artifact to {registry}. -<2> Specify the {registry} URL with the `../apis/registry/v2` endpoint. -ifdef::apicurio-registry,rh-service-registry[] +<2> Specify the {registry} URL with the `../apis/registry/v3` endpoint. <3> If authentication is required, you can specify your authentication server and client credentials. -endif::[] -ifdef::rh-openshift-sr[] -<3> Specify your service account ID and secret and the {org-name} Single Sign-On authentication server: `{sso-token-url}` -endif::[] <4> Specify the {registry} artifact group ID. You can specify the `default` group if you do not want to use a unique group ID. <5> You can register multiple artifacts using the specified group ID, artifact ID, and location. diff --git a/docs/modules/ROOT/partials/getting-started/proc-browsing-artifacts-using-console.adoc b/docs/modules/ROOT/partials/getting-started/proc-browsing-artifacts-using-console.adoc index 3fa7b0f1a2..0e6357f91b 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-browsing-artifacts-using-console.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-browsing-artifacts-using-console.adoc @@ -5,51 +5,46 @@ = Viewing artifacts using the {registry} web console [role="_abstract"] -You can use the {registry} web console to browse the schema and API artifacts stored in {registry}. This section shows a simple example of viewing {registry} artifacts, groups, versions, and artifact rules. +You can use the {registry} web console to browse the schema and API artifacts stored in {registry}. This section shows a simple example of viewing {registry} groups, artifacts, versions, and rules. .Prerequisites -ifdef::apicurio-registry,rh-service-registry[] * {registry} is installed and running in your environment. -endif::[] * You are logged in to the {registry} web console: + `{registry-url}` -ifdef::rh-openshift-sr[] -* You have access to a running {registry} instance. -endif::[] -* Artifacts have been added to {registry} using the web console, command line, Maven plug-in, or a Java client application. +* Artifacts have been added to {registry} using the web console, command line, Maven plug-in, or a client application. .Procedure -ifdef::rh-openshift-sr[] -. In the {registry} web console, click your existing {registry} instance. -endif::[] -. On the *Artifacts* tab, browse the list of artifacts stored in {registry}, or enter a search string to find an artifact. You can select from the list to search by specific criteria such as name, group, labels, or global ID. +. On the *Explore* tab, browse the list of artifacts stored in {registry}, or enter a search string to find an artifact. You can select from the list to search by specific criteria such as name, group, labels, or global ID. + .Artifacts in {registry} web console -ifdef::apicurio-registry,rh-service-registry[] image::images/getting-started/registry-web-console.png[Artifacts in Registry web console] -endif::[] -ifdef::rh-openshift-sr[] -image::../_images/user-guide/registry-web-console.png[Artifacts in Registry web console] -endif::[] + . Click an artifact to view the following details: -** *Overview*: Displays artifact version metadata such as artifact name, artifact ID, global ID, content ID, labels, properties, and so on. Also displays rules for validity and compatibility that you can configure for artifact content. -** *Documentation* (OpenAPI and AsyncAPI only): Displays automatically-generated REST API documentation. -** *Content*: Displays a read-only view of the full artifact content. For JSON content, you can click *JSON* or *YAML* to display your preferred format. -** *References*: Displays a read-only view of all artifacts referenced by this artifact. You can also click *View artifacts that reference this artifact*. +** *Overview*: Displays artifact metadata such as artifact ID, name, description, labels, and so on. Also displays rules for validity and compatibility that you can configure for artifact content. +** *Versions*: Displays a list of all artifact versions. This will be empty unless you chose to upload a first version when you created the artifact. +** *Branches*: Displays a list of branches for the artifact. This will display at least the `latest` branch, but might display other generated branches depending on your configuration. ++ +.Artifact details in {registry} web console +image::images/getting-started/registry-web-console-artifact.png[Artifacts in Registry web console] ++ +. Click the *Versions* tab to view a list of all artifact versions. Then click one of the versions in the list, or choose *View Version* from the Action menu for a version in the list. You will then see the following artifact version details: -. If additional versions of this artifact have been added, you can select them from the *Version* list in page header. +** *Overview*: Displays artifact version metadata such as version name, description, global ID, content ID, labels, and so on. Also displays any comments created for the artifact version. +** *Documentation* (OpenAPI and AsyncAPI only): Displays automatically-generated REST API documentation. +** *Content*: Displays a read-only view of the full artifact version content. For JSON content, you can click *JSON* or *YAML* to display your preferred format. +** *References*: Displays a read-only view of all artifacts referenced by this artifact version. You can also click *View artifacts that reference this artifact version*. ++ +.Artifact version details in {registry} web console +image::images/getting-started/registry-web-console-artifact-version.png[Artifacts in Registry web console] -. To save the artifact contents to a local file, for example, `my-openapi.json` or `my-protobuf-schema.proto`, and click *Download* at the end of the page. +. To save the artifact contents to a local file, for example, `my-openapi.json` or `my-protobuf-schema.proto`, and click *Download*. -ifdef::apicurio-registry,rh-service-registry[] [role="_additional-resources"] .Additional resources * xref:adding-artifacts-using-console_{context}[] * xref:configuring-rules-using-console_{context}[] * {registry-rule-reference} -endif::[] diff --git a/docs/modules/ROOT/partials/getting-started/proc-changing-artifact-owner-using-console.adoc b/docs/modules/ROOT/partials/getting-started/proc-changing-artifact-owner-using-console.adoc index 4d438f322e..df16f846ee 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-changing-artifact-owner-using-console.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-changing-artifact-owner-using-console.adoc @@ -5,19 +5,12 @@ = Changing an artifact owner using the {registry} web console [role="_abstract"] -As an administrator or as an owner of a schema or API artifact, you can use the {registry} web console to change the artifact owner to -ifdef::apicurio-registry,rh-service-registry[] -another user account. -endif::[] -ifdef::rh-openshift-sr[] -another user account or service account. -endif::[] +As an administrator or as an owner of a schema or API artifact, you can use the {registry} web console to change the artifact owner to another user account. -For example, this feature is useful if the *Artifact owner-only authorization* option is set for the {registry} instance on the *Settings* tab so that only owners or administrators can modify artifacts. You might need to change owner if the owner user leaves the organization or the owner account is deleted. +For example, this feature is useful if the *Artifact owner-only authorization* option is set for the {registry} on the *Settings* tab so that only owners or administrators can modify artifacts. You might need to change owner if the owner user leaves the organization or the owner account is deleted. Or if you simply need to transition modification authorization to a new user. + +NOTE: The *Artifact owner-only authorization* setting and the artifact *Owner* field are displayed _only if_ authentication was enabled when the {registry} was deployed. For more details, see -ifdef::apicurio-registry,rh-service-registry[] -NOTE: The *Artifact owner-only authorization* setting and the artifact *Owner* field are displayed _only if_ authentication was enabled when the {registry} instance was deployed. For more details, see -endif::[] ifdef::apicurio-registry[] xref:../getting-started/assembly-configuring-the-registry.adoc[]. endif::[] @@ -27,7 +20,7 @@ endif::[] .Prerequisites -* The {registry} instance is deployed and the artifact is created. +* The {registry} is deployed and the artifact is created. * You are logged in to the {registry} web console as the artifact's current owner or as an administrator: + `{registry-url}` @@ -35,14 +28,11 @@ endif::[] .Procedure -ifdef::rh-openshift-sr[] -. In the {registry} web console, click the {registry} instance containing the artifact that you want to reassign. -endif::[] -. On the *Artifacts* tab, browse the list of artifacts stored in {registry}, or enter a search string to find the artifact. You can select from the list to search by criteria such as name, group, labels, or global ID. +. On the *Explore* tab, browse the list of artifacts stored in {registry}, or enter a search string to find the artifact. You can select from the list to search by criteria such as name, group, labels, or global ID. . Click the artifact that you want to reassign. -. In the *Version metadata* section, click the pencil icon next to the *Owner* field. +. In the *Overview* section, click the pencil icon next to the *Owner* field. . In the *New owner* field, select or enter an account name. @@ -57,6 +47,3 @@ endif::[] ifdef::rh-service-registry[] * link:{LinkServiceRegistryInstall}[{NameServiceRegistryInstall}] endif::[] -ifdef::rh-openshift-sr[] -* link:{base-url}{access-mgmt-url-registry}[Managing account access in {product-long-registry}] -endif::[] diff --git a/docs/modules/ROOT/partials/getting-started/proc-configuring-liveness-readiness-probes.adoc b/docs/modules/ROOT/partials/getting-started/proc-configuring-liveness-readiness-probes.adoc index 04b05d7175..773be80be7 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-configuring-liveness-readiness-probes.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-configuring-liveness-readiness-probes.adoc @@ -3,7 +3,7 @@ [id="configuring-liveness-readiness-probes_{context}"] -= Configuring {registry} health checks on OpenShift +== Configuring {registry} health checks on OpenShift [role="_abstract"] You can configure optional environment variables for liveness and readiness probes to monitor the health of the {registry} server on OpenShift: @@ -17,7 +17,7 @@ IMPORTANT: The default values of the liveness and readiness environment variable .Prerequisites * You must have an OpenShift cluster with cluster administrator access. * You must have already installed {registry} on OpenShift. -* You must have already installed and configured your chosen {registry} storage in {kafka-streams} or PostgreSQL. +* You must have already installed and configured your chosen {registry} storage in either {kafka-streams} or PostgreSQL. .Procedure diff --git a/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-logging.adoc b/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-logging.adoc deleted file mode 100644 index dedce21bda..0000000000 --- a/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-logging.adoc +++ /dev/null @@ -1,43 +0,0 @@ -[id="registry-logging_{context}"] -= Configuring {registry} logging - -You can set {registry} logging configuration at runtime. {registry} provides a REST endpoint to set the log level for specific loggers for finer grained logging. This section explains how to view and set {registry} log levels at runtime using the {registry} `/admin` REST API. - -.Prerequisites - -* Get the URL to access your {registry} instance, or get your {registry} route if you have {registry} deployed on OpenShift. This simple example uses a URL of `localhost:8080`. - -.Procedure - -. Use this `curl` command to obtain the current log level for the logger `io.apicurio.registry.storage`: -+ -[source,bash] ----- -$ curl -i localhost:8080/apis/registry/v2/admin/loggers/io.apicurio.registry.storage -HTTP/1.1 200 OK -[...] -Content-Type: application/json -{"name":"io.apicurio.registry.storage","level":"INFO"} ----- - -. Use this `curl` command to change the log level for the logger `io.apicurio.registry.storage` to `DEBUG`: -+ -[source,bash] ----- -$ curl -X PUT -i -H "Content-Type: application/json" --data '{"level":"DEBUG"}' localhost:8080/apis/registry/v2/admin/loggers/io.apicurio.registry.storage -HTTP/1.1 200 OK -[...] -Content-Type: application/json -{"name":"io.apicurio.registry.storage","level":"DEBUG"} ----- - -. Use this `curl` command to revert the log level for the logger `io.apicurio.registry.storage` to its default value: -+ -[source,bash] ----- -$ curl -X DELETE -i localhost:8080/apis/registry/v2/admin/loggers/io.apicurio.registry.storage -HTTP/1.1 200 OK -[...] -Content-Type: application/json -{"name":"io.apicurio.registry.storage","level":"INFO"} ----- diff --git a/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-security-azure.adoc b/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-security-azure.adoc index ce706365af..df04a13006 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-security-azure.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-security-azure.adoc @@ -48,10 +48,10 @@ IMPORTANT: You must register your {registry} application host as a *Redirect URI |`KEYCLOAK_API_CLIENT_ID` |The client application ID for the {registry} REST API |Your Azure AD Application (client) ID obtained in step 5. For example: `123456a7-b8c9-012d-e3f4-5fg67h8i901` -|`REGISTRY_OIDC_UI_CLIENT_ID` +|`APICURIO_OIDC_UI_CLIENT_ID` |The client application ID for the {registry} web console. |Your Azure AD Application (client) ID obtained in step 5. For example: `123456a7-b8c9-012d-e3f4-5fg67h8i901` -|`REGISTRY_AUTH_URL_CONFIGURED` +|`APICURIO_AUTH_URL_CONFIGURED` |The URL for authentication in Azure AD. |Your Azure AD Application (tenant) ID obtained in step 6. For example: `\https://login.microsoftonline.com/1a2bc34d-567e-89f1-g0hi-1j2kl3m4no56/v2.0`. |=== @@ -64,16 +64,16 @@ IMPORTANT: You must register your {registry} application host as a *Redirect URI |Environment variable |Description |Setting -|`REGISTRY_AUTH_ENABLED` +|`APICURIO_AUTH_ENABLED` |Enables authentication for {registry}. |`true` -|`REGISTRY_UI_AUTH_TYPE` +|`APICURIO_UI_AUTH_TYPE` |The {registry} authentication type. |`oidc` |`CORS_ALLOWED_ORIGINS` |The host for your {registry} deployment for cross-origin resource sharing (CORS). |For example: `\https://test-registry.com` -|`REGISTRY_OIDC_UI_REDIRECT_URL` +|`APICURIO_OIDC_UI_REDIRECT_URL` |The host for your {registry} web console. |For example: `\https://test-registry.com/ui` |`APICURIO_AUTH_ROLE_BASED_AUTHORIZATION` diff --git a/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-security-keycloak.adoc b/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-security-keycloak.adoc index 117bcfd798..35eeb2b010 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-security-keycloak.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-security-keycloak.adoc @@ -144,7 +144,7 @@ TIP: For an example of setting environment variables on OpenShift, see xref:conf |Java system property |Type |Default value -|`REGISTRY_AUTH_OBAC_ENABLED` +|`APICURIO_AUTH_OWNER_ONLY_AUTHORIZATION` |`apicurio.auth.owner-only-authorization` |Boolean |`false` diff --git a/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-ui.adoc b/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-ui.adoc index cf24d8aa86..0be52a4eb6 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-ui.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-ui.adoc @@ -11,24 +11,23 @@ You can set optional environment variables to configure the {registry} web conso [discrete] == Configuring the web console deployment environment -When you access the {registry} web console in your browser, some initial configuration settings are loaded. The following configuration settings are important: +When you access the {registry} web console in your browser, some initial configuration settings are loaded. The following configuration settings are required: -* URL for core {registry} server REST API -* URL for {registry} web console client +* URL for core {registry} server REST API v3 -Typically, {registry} automatically detects and generates these settings, but there are some deployment environments where this automatic detection can fail. If this happens, you can configure environment variables to explicitly set these URLs for your environment. +Typically the {registry} operator will automatically configure the UI component with the REST API v3 URL. However, you can override this value by configuring the appropriate environment variable in the UI component deployment configuration. .Procedure -Configure the following environment variables to override the default URLs: +Configure the following environment variables to override the default URL: -* `REGISTRY_UI_CONFIG_APIURL`: Specifies the URL for the core {registry} server REST API. For example, `\https://registry.my-domain.com/apis/registry` -* `REGISTRY_UI_CONFIG_UIURL`: Specifies the URL for the {registry} web console client. For example, `\https://registry.my-domain.com/ui` +* `REGISTRY_API_URL`: Specifies the URL for the core {registry} server REST API v3. For example, `\https://registry-api.my-domain.com/apis/registry/v3` [discrete] == Configuring the web console in read-only mode You can configure the {registry} web console in read-only mode as an optional feature. This mode disables all features in the {registry} web console that allow users to make changes to registered artifacts. For example, this includes the following: +* Creating a group * Creating an artifact * Uploading a new artifact version * Updating artifact metadata @@ -37,4 +36,4 @@ You can configure the {registry} web console in read-only mode as an optional fe .Procedure Configure the following environment variable: -* `REGISTRY_UI_FEATURES_READONLY`: Set to `true` to enable read-only mode. Defaults to `false`. +* `REGISTRY_FEATURE_READ_ONLY`: Set to `true` to enable read-only mode. Defaults to `false`. diff --git a/docs/modules/ROOT/partials/getting-started/proc-configuring-rules-using-console.adoc b/docs/modules/ROOT/partials/getting-started/proc-configuring-rules-using-console.adoc index ac3aff446e..86b8c5d52f 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-configuring-rules-using-console.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-configuring-rules-using-console.adoc @@ -5,48 +5,49 @@ = Configuring content rules using the {registry} web console [role="_abstract"] -You can use the {registry} web console to configure optional rules to prevent invalid or incompatible content from being added to {registry}. All configured artifact-specific rules or global rules must pass before a new artifact version can be uploaded to {registry}. Configured artifact-specific rules override any configured global rules. This section shows a simple example of configuring global and artifact-specific rules. +You can use the {registry} web console to configure optional rules to prevent invalid or incompatible content from being added to {registry}. All configured artifact-specific, group-specific, or global rules must pass before a new artifact version can be uploaded to {registry}. Configured artifact-specific rules override any configured group-specific rules, which in turn override any global rules. This section shows a simple example of configuring global, group-specific, and artifact-specific rules. .Prerequisites -ifdef::apicurio-registry,rh-service-registry[] * {registry} is installed and running in your environment. -endif::[] * You are logged in to the {registry} web console: + `{registry-url}` -ifdef::rh-openshift-sr[] -* You have access to a running {registry} instance. -endif::[] -* Artifacts have been added to {registry} using the web console, command line, Maven plug-in, or a Java client application. -* When role-based authorization is enabled, you have administrator access for global rules and artifact-specific rules, or developer access for artifact-specific rules only. +* Artifacts have been added to {registry} using the web console, command line, Maven plug-in, or a Java client application. +* When role-based authorization is enabled, you have administrator access for global rules configuration. -.Procedure - -ifdef::rh-openshift-sr[] -. In the {registry} web console, click your existing {registry} instance. -endif::[] -. On the *Artifacts* tab, browse the list of artifacts in {registry}, or enter a search string to find an artifact. You can select from the list to search by specific criteria such as artifact name, group, labels, or global ID. +.Procedure (group-specific rules) +. On the *Explore* tab, browse the list of groups in {registry} by selecting *Groups* from the "Search for" menu. ++ +. Click a group to view its details and content rules. ++ +. In *Group-specific rules*, click *Enable* to configure a validity, compatibility, or integrity rule for all artifact content in the group, and select the appropriate rule configuration from the list. For example, for *Validity rule*, select *Full*. ++ +.Group-specific rules in {registry} web console +image::images/getting-started/registry-web-console-group-rules.png[Configure group-specific rules in Registry web console] -. Click an artifact to view its version details and content rules. -. In *Artifact-specific rules*, click *Enable* to configure a validity, compatibility, or integrity rule for artifact content, and select the appropriate rule configuration from the list. For example, for *Validity rule*, select *Full*. +.Procedure (artifact-specific rules) +. On the *Explore* tab, browse the list of artifacts in {registry} by selecting *Artifacts* from the "Search for" menu. ++ +. Click an artifact from the list to view its details and content rules. ++ +. In *Artifact-specific rules*, click *Enable* to configure a validity, compatibility, or integrity rule for artifact content, and select the appropriate rule configuration from the list. For example, for *Validity rule*, select *Full*. + .Artifact content rules in {registry} web console -ifdef::apicurio-registry,rh-service-registry[] -image::images/getting-started/registry-web-console-rules.png[Configure rules in Registry web console] -endif::[] -ifdef::rh-openshift-sr[] -image::../_images/user-guide/registry-web-console-rules.png[Configure rules in Registry web console] -endif::[] +image::images/getting-started/registry-web-console-artifact-rules.png[Configure rules in Registry web console] + + +.Procedure (global rules) +. To access global rules, click the *Global rules* tab. +. Click *Enable* to configure global validity, compatibility, or integrity rules for all artifact content, and select the appropriate rule configuration from the list. + -. To access global rules, click the *Global rules* tab. Click *Enable* to configure global validity, compatibility, or integrity rules for all artifact content, and select the appropriate rule configuration from the list. +.Artifact content rules in {registry} web console +image::images/getting-started/registry-web-console-global-rules.png[Configure rules in Registry web console] -. To disable an artifact rule or global rule, click the trash icon next to the rule. +NOTE: To disable an artifact-specific, group-specific, or global rule, click the trash icon next to the rule. If you do this, and the rule is configured at a higher level (e.g. Global), then the higher level rule configuration will once again be applied. -ifdef::apicurio-registry,rh-service-registry[] [role="_additional-resources"] .Additional resources * xref:adding-artifacts-using-console_{context}[] * {registry-rule-reference} -endif::[] diff --git a/docs/modules/ROOT/partials/getting-started/proc-configuring-settings-using-console.adoc b/docs/modules/ROOT/partials/getting-started/proc-configuring-settings-using-console.adoc index 1836e0f501..b53f9fa91a 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-configuring-settings-using-console.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-configuring-settings-using-console.adoc @@ -2,16 +2,14 @@ // ParentAssemblies: assemblies/getting-started/as_managing-registry-artifacts.adoc [id="configuring-settings-using-console_{context}"] -= Configuring {registry} instance settings using the web console += Configuring {registry} settings using the web console [role="_abstract"] -As an administrator, you can use the {registry} web console to configure dynamic settings for {registry} instances at runtime. You can manage configuration options for features such as authentication, authorization, and API compatibility. +As an administrator, you can use the {registry} web console to configure dynamic settings for {registry} at runtime. You can manage configuration options for features such as authentication, authorization, and API compatibility. //This section shows how to configure.. -ifdef::apicurio-registry,rh-service-registry[] -NOTE: Authentication and authorization settings are only displayed in the web console if authentication was already enabled when the {registry} instance was deployed. For more details, see -endif::[] +NOTE: Authentication and authorization settings are only displayed in the web console if authentication was already enabled when the {registry} was deployed. For more details, see ifdef::apicurio-registry[] xref:../getting-started/assembly-configuring-the-registry.adoc[]. endif::[] @@ -21,22 +19,16 @@ endif::[] .Prerequisites -* The {registry} instance is already deployed. +* The {registry} is already deployed. * You are logged in to the {registry} web console with administrator access: + `{registry-url}` .Procedure -ifdef::apicurio-registry,rh-service-registry[] -. In the {registry} web console, click the *Settings* tab. -endif::[] - -ifdef::rh-openshift-sr[] -. In the {registry} web console, click the {registry} instance that you want to configure, and then click the *Settings* tab. -endif::[] +. In the {registry} web console, click the *Settings* tab. -. Select the settings that you want to configure for this {registry} instance: +. Select the settings that you want to configure for {registry}: + .Authentication settings [%header,cols="2,4"] @@ -44,17 +36,9 @@ endif::[] |Setting |Description |*HTTP basic authentication* -| -ifdef::apicurio-registry,rh-service-registry[] -Displayed only when authentication is already enabled. -endif::[] -When selected, {registry} users can authenticate using HTTP basic authentication, in addition to OAuth. -ifdef::apicurio-registry,rh-service-registry[] -Not selected by default. -endif::[] -ifdef::rh-openshift-sr[] -Selected by default. -endif::[] +|Displayed only when authentication is already enabled (during deployment). +When selected, {registry} users can authenticate using HTTP basic authentication, in addition to OAuth. +Not selected by default. |=== + .Authorization settings @@ -62,32 +46,14 @@ endif::[] |=== |Setting |Description -ifdef::apicurio-registry,rh-service-registry[] | *Anonymous read access* -|Displayed only when authentication is already selected. -When selected, {registry} grants read-only access to requests from anonymous users without any credentials. This setting is useful if you want to use this instance to publish schemas or APIs externally. Not selected by default. -endif::[] +|Displayed only when authentication is already enabled. When selected, {registry} grants read-only access to requests from anonymous users without any credentials. This setting is useful if you want to use {registry} to publish schemas or APIs externally. Not selected by default. | *Artifact owner-only authorization* -| -ifdef::apicurio-registry,rh-service-registry[] -Displayed only when authentication is already enabled. -endif::[] -When selected, only the user who created an artifact can modify that artifact. Not selected by default. -ifdef::apicurio-registry,rh-service-registry[] +|Displayed only when authentication is already enabled. When selected, only the user who created an artifact can modify that artifact. Not selected by default. | *Artifact group owner-only authorization* -|Displayed only when authentication is already enabled and *Artifact owner-only authorization* is selected. -When selected, only the user who created an artifact group has write access to that artifact group, for example, to add or remove artifacts in that group. Not selected by default. -endif::[] +|Displayed only when authentication is already enabled and *Artifact owner-only authorization* is also enabled. When selected, only the user who created an artifact group has write access to that artifact group, for example, to add or remove artifacts in that group. Not selected by default. | *Authenticated read access* -| -ifdef::apicurio-registry,rh-service-registry[] -Displayed only when authentication is already enabled. -endif::[] -When selected, {registry} grants at least read-only access to requests from any authenticated user -ifdef::rh-openshift-sr[] -in the same organization, -endif::[] -regardless of their user role. Not selected by default. +|Displayed only when authentication is already enabled. When selected, {registry} grants at least read-only access to requests from any authenticated user regardless of their user role. Not selected by default. |=== + .Compatibility settings @@ -95,30 +61,47 @@ regardless of their user role. Not selected by default. |=== |Setting |Description +| *Canonical hash mode (compatibility API)* +| When selected, the Schema Registry compatibility API uses the canonical hash instead of the regular hash of the content. | *Legacy ID mode (compatibility API)* -| When selected, the Confluent Schema Registry compatibility API uses `globalId` instead of `contentId` as an artifact identifier. This setting is useful when migrating from legacy {registry} instances based on the v1 Core Registry API. Not selected by default. +| When selected, the Confluent Schema Registry compatibility API uses `globalId` instead of `contentId` as an artifact identifier. +| *Maximum number of Subjects returned (compatibility API)* +| Determines the maximum number of Subjects that will be returned by the Confluent Schema Registry compatibility API (for the `/subjects` endpoint). |=== + -ifdef::apicurio-registry,rh-service-registry[] .Web console settings [%header,cols="2,4"] |=== |Setting |Description |*Download link expiry* -| The number of seconds that a generated link to a `.zip` download file is active before expiring for security reasons, for example, when exporting artifact data from the instance. Defaults to 30 seconds. -| *UI read-only mode* -| When selected, the {registry} web console is set to read-only, preventing create, read, update, or delete operations. Changes made using the Core Registry API are not affected by this setting. Not selected by default. +| The number of seconds that a generated link to a `.zip` download file is active before expiring for security reasons, for example, when exporting artifact data from {registry}. Defaults to 30 seconds. +|=== ++ +.Semantic versioning settings +[%header,cols="2,4"] +|=== +|Setting +|Description +|*Automatically create semver branches* +| When enabled, automatically create or update branches for major ('A.x') and minor ('A.B.x') artifact versions. +|*Ensure all version numbers are 'semver' compatible* +| When enabled, validate that all artifact versions conform to Semantic Versioning 2 format (https://semver.org). |=== -endif::[] + .Additional properties [%header,cols="2,4"] |=== |Setting |Description +| *Delete artifact* +| When selected, users are permitted to delete artifacts in {registry} by using the Core Registry API. Not selected by default. | *Delete artifact version* -| When selected, users are permitted to delete artifact versions in this instance by using the Core Registry API. Not selected by default. +| When selected, users are permitted to delete artifact versions in {registry} by using the Core Registry API. Not selected by default. +| *Delete group* +| When selected, users are permitted to delete groups in {registry} by using the Core Registry API. Not selected by default. +| *Storage read-only mode* +| When selected, Registry will return an error for operations that write to the storage (this property excepted). Not enabled by default. |=== @@ -130,6 +113,3 @@ endif::[] ifdef::rh-service-registry[] * link:{LinkServiceRegistryInstall}[{NameServiceRegistryInstall}] endif::[] -ifdef::rh-openshift-sr[] -* link:{base-url}{access-mgmt-url-registry}[Managing account access in {product-long-registry}] -endif::[] diff --git a/docs/modules/ROOT/partials/getting-started/proc-creating-access-token-rest-api.adoc b/docs/modules/ROOT/partials/getting-started/proc-creating-access-token-rest-api.adoc index 30fe428396..7aaf32332c 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-creating-access-token-rest-api.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-creating-access-token-rest-api.adoc @@ -5,16 +5,11 @@ = Creating an access token for {registry} REST API commands [role="_abstract"] -This section shows a curl-based example of how to create an OAuth Bearer access token for use with the Core Registry API v2. You can do this using the OpenShift Application Services authentication server and your service account credentials. +This section shows a curl-based example of how to create an OAuth Bearer access token for use with the Core Registry API v3. You can do this using the OpenShift Application Services authentication server and your service account credentials. .Prerequisites -ifdef::apicurio-registry,rh-service-registry[] * {registry} is installed and running in your environment -endif::[] -ifdef::rh-openshift-sr[] -* You have access to the {registry} web console. -endif::[] .Procedure diff --git a/docs/modules/ROOT/partials/getting-started/proc-downloading-artifacts-using-maven-plugin.adoc b/docs/modules/ROOT/partials/getting-started/proc-downloading-artifacts-using-maven-plugin.adoc index a22d29dcfe..74dd30f59c 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-downloading-artifacts-using-maven-plugin.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-downloading-artifacts-using-maven-plugin.adoc @@ -26,7 +26,7 @@ You can use the Maven plug-in to download artifacts from {registry}. This is oft download <1> - MY-REGISTRY-URL/apis/registry/v2 <2> + MY-REGISTRY-URL/apis/registry/v3 <2> MY-AUTH-SERVER MY-CLIENT-ID MY-CLIENT-SECRET <3> @@ -53,13 +53,8 @@ You can use the Maven plug-in to download artifacts from {registry}. This is oft ---- + <1> Specify `download` as the execution goal. -<2> Specify the {registry} URL with the `../apis/registry/v2` endpoint. -ifdef::apicurio-registry,rh-service-registry[] +<2> Specify the {registry} URL with the `../apis/registry/v3` endpoint. <3> If authentication is required, you can specify your authentication server and client credentials. -endif::[] -ifdef::rh-openshift-sr[] -<3> Specify your service account ID and secret and {org-name} Single Sign-On authentication server: `{sso-token-url}` -endif::[] <4> Specify the {registry} artifact group ID. You can specify the `default` group if you do not want to use a unique group. <5> You can download multiple artifacts to a specified directory using the artifact ID. diff --git a/docs/modules/ROOT/partials/getting-started/proc-exporting-importing-using-rest-api.adoc b/docs/modules/ROOT/partials/getting-started/proc-exporting-importing-using-rest-api.adoc index c6137f5a1e..2d7a32ea35 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-exporting-importing-using-rest-api.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-exporting-importing-using-rest-api.adoc @@ -5,37 +5,23 @@ = Exporting and importing registry data using {registry} REST API commands [role="_abstract"] -As an administrator, you can use the Core Registry API v2 to export data from one {registry} instance and import into another {registry} instance, so you can migrate data between different instances. +As an administrator, you can use the Core Registry API v3 to export data from one {registry} instance and import into another {registry} instance, so you can migrate data between different instances. -This section shows a simple curl-based example of using the Core Registry API v2 to export and import existing data in `.zip` format from one {registry} instance to another. All of the artifact data contained in the {registry} instance is exported in the `.zip` file. - -NOTE: You can import only {registry} data that has been exported from another {registry} instance. +This section shows a simple curl-based example of using the Core Registry API v3 to export and import existing data in `.zip` format from one {registry} instance to another. All the artifact data contained in the {registry} instance is exported in the `.zip` file. .Prerequisites -ifdef::apicurio-registry,rh-service-registry[] * {registry} is installed and running in your environment. -endif::[] * {registry} instances have been created: ** The source instance that you want to export data from contains at least one schema or API artifact. ** The target instance that you want to import data into is empty to preserve unique IDs. -ifdef::rh-openshift-sr[] -* You have a service account with administrator access to the {registry} instances. -* You have created an access token using your service account credentials. -* You have logged in to the {registry-url}[{registry} web console]. -endif::[] .Procedure -ifdef::rh-openshift-sr[] -. In the {registry} web console, for the {registry} instance that you want to connect to, select the options icon (three vertical dots) and click *Connection*. -. In the *Connection* page, copy the URL for the *Core Registry API* to a secure location. You will use this API endpoint to connect to the {registry} instance. -endif::[] - . Export the {registry} data from your existing source {registry} instance: + [source,bash] ---- -$ curl MY-REGISTRY-URL/apis/registry/v2/admin/export \ +$ curl MY-REGISTRY-URL/apis/registry/v3/admin/export \ -H "Authorization: Bearer $ACCESS_TOKEN" \ --output my-registry-data.zip ---- @@ -47,15 +33,12 @@ endif::[] ifdef::rh-service-registry[] host name on which the source {registry} is deployed. For example: `my-cluster-source-registry-myproject.example.com`. endif::[] -ifdef::rh-openshift-sr[] -Core Registry API endpoint that you copied to connect to this {registry} instance. For example: `\https://service-registry-source.apps.app-sre-0.k3s7.p1.openshiftapps.com/t/f301375a-18a7-426c-bbd8-8e626a0a1d0e`. -endif::[] . Import the registry data into your target {registry} instance: + [source,bash] ---- -$ curl -X POST "MY-REGISTRY-URL/apis/registry/v2/admin/import" \ +$ curl -X POST "MY-REGISTRY-URL/apis/registry/v3/admin/import" \ -H "Content-Type: application/zip" -H "Authorization: Bearer $ACCESS_TOKEN" \ --data-binary @my-registry-data.zip ---- @@ -67,14 +50,9 @@ endif::[] ifdef::rh-service-registry[] host name on which the target {registry} is deployed. For example: `my-cluster-target-registry-myproject.example.com`. endif::[] -ifdef::rh-openshift-sr[] -Core Registry API endpoint that you copied to connect to this {registry} instance. For example: `\https://service-registry-target.apps.app-sre-0.k3s7.p1.openshiftapps.com/t/f301375a-18a7-426c-bbd8-8e626a0a1d0e`. -endif::[] [role="_additional-resources"] .Additional resources * For more details, see the `admin` endpoint in the {registry-rest-api}. -ifdef::apicurio-registry,rh-service-registry[] * For details on export tools for migrating from {registry} version 1.x to 2.x, see link:https://github.com/Apicurio/apicurio-registry/tree/main/utils/exportV1[Apicurio Registry export utility for 1.x versions]. -endif::[] diff --git a/docs/modules/ROOT/partials/getting-started/proc-exporting-importing-using-web-console.adoc b/docs/modules/ROOT/partials/getting-started/proc-exporting-importing-using-web-console.adoc index 25cba8df59..3b3b4d6825 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-exporting-importing-using-web-console.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-exporting-importing-using-web-console.adoc @@ -7,13 +7,7 @@ [role="_abstract"] As an administrator, you can use the {registry} web console to export data from one {registry} instance, and import this data into another {registry} instance. You can use this feature to easily migrate data between different instances. -The following example shows how to export and import existing data in a `.zip` file from one {registry} instance to another instance. All of the artifact data contained in the {registry} instance is exported in the `.zip` file. - -NOTE: You can import only {registry} data that has been exported from another {registry} instance. - -ifdef::rh-openshift-sr[] -This example shows exporting and importing {registry} data from the *Artifacts* tab for that instance. You can also export {registry} data when prompted before deleting an instance. -endif::[] +The following example shows how to export and import existing data in a `.zip` file from one {registry} instance to another instance. All the artifact data contained in the {registry} instance is exported in the `.zip` file. .Prerequisites @@ -26,29 +20,17 @@ endif::[] .Procedure -ifdef::apicurio-registry,rh-service-registry[] -. In the web console for the source {registry} instance, view the *Artifacts* tab. -endif::[] - -ifdef::rh-openshift-sr[] -. In the web console, in the list of instances, click the source {registry} instance, and view the *Artifacts* tab. -endif::[] - -. Click the options icon (three vertical dots) next to *Upload artifact*, and select *Download all artifacts (.zip file)* to export the data for this {registry} instance to a `.zip` download file. +. In the web console for the source {registry} instance, view the *Explore* tab. -ifdef::apicurio-registry,rh-service-registry[] -. In the the web console for the target {registry} instance, view the *Artifacts* tab. -endif::[] +. Click the additional actions icon (three vertical dots) next to *Create artifact* in the toolbar, and select *Export all (as .ZIP)* to export the data for this {registry} instance to a `.zip` download file. -ifdef::rh-openshift-sr[] -. Return to the list of instances, click the target {registry} instance, and view the *Artifacts* tab. -endif::[] +. In the web console for the target {registry} instance, view the *Explore* tab. -. Click the options icon next to *Upload artifact*, and select *Upload multiple artifacts*. +. Click the additional actions icon (three vertical dots) next to *Create artifact* in the toolbar, and select *Import from .ZIP*. . Drag and drop or browse to the `.zip` download file that you exported earlier. -. Click *Upload* and wait for the data to be imported. +. Click *Import* and wait for the data to be imported. //[role="_additional-resources"] //.Additional resources diff --git a/docs/modules/ROOT/partials/getting-started/proc-generating-client-sdk-using-web-console.adoc b/docs/modules/ROOT/partials/getting-started/proc-generating-client-sdk-using-web-console.adoc deleted file mode 100644 index 74c159e9cb..0000000000 --- a/docs/modules/ROOT/partials/getting-started/proc-generating-client-sdk-using-web-console.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Metadata created by nebel -// ParentAssemblies: assemblies/getting-started/as_managing-registry-artifacts.adoc - -[id="generating-client-sdk-using-web-console_{context}"] -= Generating client SDKs for OpenAPI artifacts using the {registry} web console - -[role="_abstract"] -You can use the {registry} web console to configure, generate, and download client software development kits (SDKs) for OpenAPI artifacts. You can then use the generated client SDKs to build your client applications for specific platforms based on the OpenAPI. - -{registry} generates client SDKs for the following programming languages: - - * C# - * Go - * Java - * PHP - * Python - * Ruby - * Swift - * TypeScript - -NOTE: Client SDK generation for OpenAPI artifacts runs in your browser only, and cannot be automated by using an API. You must regenerate the client SDK each time a new artifact version is added in {registry}. - -.Prerequisites - -* {registry} is installed and running in your environment. - -* You are logged in to the {registry} web console: -+ -`{registry-url}` - -* An OpenAPI artifact has been added to {registry} using the web console, command line, Maven plug-in, or a Java client application. - -.Procedure - -. On the *Artifacts* tab, browse the list of artifacts stored in {registry}, or enter a search string to find a specific OpenAPI artifact. You can select from the list to search by criteria such as name, group, labels, or global ID. - -. Click the OpenAPI artifact in the list to view its details. - -. In the *Version metadata* section, click *Generate client SDK*, and configure the following settings in the dialog: - -** *Language*: Select the programming language in which to generate the client SDK, for example, *Java*. -** *Generated client class name*: Enter the class name for the client SDK, for example, `MyJavaClientSDK.` -** *Generated client package name*: Enter the package name for the client SDK, for example, `io.my.example.sdk` - -. Click *Show advanced settings* to configure optional comma-separated lists of path patterns to include or exclude: -** *Include path patterns*: Enter specific paths to include when generating the client SDK, for example, `\\**/.*, \**/my-path/*`. If this field is empty, all paths are included. -** *Exclude path patterns*: Enter specific paths to exclude when generating the client SDK, for example, `\**/my-other-path/*`. If this field is empty, no paths are excluded. -+ -.Generate a Java client SDK in {registry} web console -image::images/getting-started/registry-web-console-client-sdk.png[Generate a Java client SDK in the registry web console] - -. When you have configured the settings in the dialog, click *Generate and download*. - -. Enter a file name for the client SDK in the dialog, for example, `my-client-java.zip`, and click *Save* to download. - -[role="_additional-resources"] -.Additional resources -* {registry} uses Kiota from Microsoft to generate the client SDKs. For more information, see the https://github.com/microsoft/kiota[Kiota project in GitHub^]. -* For more details and examples of using the generated SDKs to build client applications, see the https://learn.microsoft.com/en-us/openapi/kiota[Kiota documentation^]. \ No newline at end of file diff --git a/docs/modules/ROOT/partials/getting-started/proc-installing-registry-in-memory-storage.adoc b/docs/modules/ROOT/partials/getting-started/proc-installing-registry-in-memory-storage.adoc index 96777d3ddb..adaa229e8b 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-installing-registry-in-memory-storage.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-installing-registry-in-memory-storage.adoc @@ -5,14 +5,14 @@ = Installing {registry} with in-memory storage [role="_abstract"] -This section explains how to install and run {registry} with simple in-memory storage from a container image. +This section explains how to install and run {registry} with simple in-memory storage from a container image. -NOTE: The in-memory storage option is suitable for development only. All data is lost when the container image is restarted. +NOTE: The in-memory storage option is suitable for development only. All data is lost when the container image is restarted. .Prerequisites * You must have Docker installed and the Docker daemon running. -* Ensure that you can connect to the container repository: https://hub.docker.com/r/apicurio/apicurio-registry-mem. +* Ensure that you can connect to the container repository: https://hub.docker.com/r/apicurio/apicurio-registry. .Procedure @@ -20,23 +20,25 @@ NOTE: The in-memory storage option is suitable for development only. All data is + [source,bash] ---- -$ docker pull apicurio/apicurio-registry-mem:VERSION +$ docker pull apicurio/apicurio-registry:VERSION ---- + -`VERSION` is the {registry} release version, for example, `{registry-docker-version}`. For more details, see https://hub.docker.com/r/apicurio/apicurio-registry-mem/tags. +`VERSION` is the {registry} release version, for example, `{registry-docker-version}`. For more details, see https://hub.docker.com/r/apicurio/apicurio-registry/tags. . Run the container image: + [source,bash] ---- -$ docker run -it -p 8080:8080 apicurio/apicurio-registry-mem:VERSION +$ docker run -it -p 8080:8080 apicurio/apicurio-registry:VERSION ---- +NOTE: All storage variants of {registry} 3.x now share the same container image of `apicurio/apicurio-registry`. This is in contrast to the separate container images used by {registry} 2.x. Choosing a storage variant is now a matter of configuring the single backend/server container image. + . Send a test request using the {registry} REST API. For example, enter the following `curl` command to create a simple Avro schema artifact for a share price application in the registry: + [source,bash] ---- -$ 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://localhost:8080/apis/registry/v2/groups/my-group/artifacts +$ 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://localhost:8080/apis/registry/v3/groups/my-group/artifacts ---- . Verify that the response includes the expected JSON body to confirm that the Avro schema artifact was created in the registry. For example: diff --git a/docs/modules/ROOT/partials/getting-started/proc-installing-registry-kafka-storage.adoc b/docs/modules/ROOT/partials/getting-started/proc-installing-registry-kafka-storage.adoc index 3e14b53f25..251f4ed9c5 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-installing-registry-kafka-storage.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-installing-registry-kafka-storage.adoc @@ -11,13 +11,13 @@ ifdef::rh-service-registry[] endif::[] [role="_abstract"] -This topic explains how to install and run {registry} with Kafka storage from a container image. The `kafkasql` storage option uses Kafka storage with in-memory H2 database. This storage option is suitable for production environments. +This topic explains how to install and run {registry} with Kafka storage from a container image. The `kafkasql` storage option uses a Kafka topic for storage, along with an in-memory H2 database. This storage option is suitable for production environments. .Prerequisites * You must have Docker installed and the Docker daemon running. ifdef::apicurio-registry[] -* Ensure that you can connect to the container repository: https://hub.docker.com/r/apicurio/apicurio-registry-kafkasql. +* Ensure that you can connect to the container repository: https://hub.docker.com/r/apicurio/apicurio-registry. endif::[] * Ensure that `KAFKA_HOME` is set to the location of your Kafka-based system. * You must already have your Kafka broker running. For example: @@ -28,7 +28,7 @@ $KAFKA_HOME/bin/zookeeper-server-start.sh $KAFKA_HOME/config/zookeeper.propertie $KAFKA_HOME/bin/kafka-server-start.sh $KAFKA_HOME/config/server.properties & ---- + -For more details, see https://kafka.apache.org/quickstart. +For more details, see https://kafka.apache.org/quickstart. .Procedure ifdef::apicurio-registry[] @@ -36,20 +36,21 @@ ifdef::apicurio-registry[] + [source,bash] ---- -$ docker pull apicurio/apicurio-registry-kafkasql:VERSION +$ docker pull apicurio/apicurio-registry:VERSION ---- + -`VERSION` is the {registry} release version, for example, `{registry-docker-version}`. For more details, see https://hub.docker.com/r/apicurio/apicurio-registry-kafkasql/tags. +`VERSION` is the {registry} release version, for example, `{registry-docker-version}`. For more details, see https://hub.docker.com/r/apicurio/apicurio-registry/tags. -. Run the container image and specify the following environment variable for your Kafka system: +. Run the container image and specify the following environment variable for your Kafka system: + -** `KAFKA_BOOTSTRAP_SERVERS` - The address(es) of your Kafka broker(s). +** `APICURIO_STORAGE_KIND` - Set this to `kafkasql` +** `APICURIO_KAFKA_BOOTSTRAP_SERVERS` - The address(es) of your Kafka broker(s). + For example: + [source,bash] ---- -$ docker run -it -p 8080:8080 -e "KAFKA_BOOTSTRAP_SERVERS=kafka:9092" apicurio/apicurio-registry-kafkasql:latest +$ docker run -it -p 8080:8080 -e "APICURIO_STORAGE_KIND=kafkasql" -e "APICURIO_KAFKA_BOOTSTRAP_SERVERS=kafka:9092" apicurio/apicurio-registry:latest ---- endif::[] @@ -64,7 +65,7 @@ $ docker login registry.redhat.io + [source,bash] ---- -$ docker pull registry.redhat.io/fuse7-tech-preview/fuse-service-registry-rhel7 +$ docker pull registry.redhat.io/fuse7-tech-preview/fuse-service-registry-rhel7 ---- . Run the container image and specify the following environment variable for your Kafka system: + @@ -82,13 +83,13 @@ endif::[] + [source,bash] ---- -$ 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://localhost:8080/apis/registry/v2/groups/my-group/artifacts +$ curl -X POST -H "Content-type: application/json" --data '{"artifactId":"share-price","artifactType":"AVRO","name":"Share Price","labels":{"environment":"DEV","category":"finance"},"firstVersion":{"version":"1.0.0","content":{"content":"{\"type\":\"record\",\"name\":\"price\",\"namespace\":\"com.example\",\"fields\":[{\"name\":\"symbol\",\"type\":\"string\"},{\"name\":\"price\",\"type\":\"string\"}]}","contentType":"application/json"}}}' http://localhost:8080/apis/registry/v3/groups/my-group/artifacts ---- . Verify that the response includes the expected JSON body to confirm that the Avro schema artifact was created in the registry. For example: + [source,bash] ---- -{"name":"price","createdBy":"","createdOn":"2021-03-19T17:48:17+0000","modifiedOn":"2021-03-19T17:48:17+0000","id":"share-price","version":1,"type":"AVRO","globalId":12,"state":"ENABLED","groupId":"my-group","contentId":12} +{"artifact":{"name":"Share Price","owner":"","createdOn":"2024-09-26T16:26:03Z","modifiedBy":"","modifiedOn":"2024-09-26T16:26:03Z","artifactType":"AVRO","labels":{"environment":"DEV","category":"finance"},"groupId":"my-group","artifactId":"share-price"},"version":{"version":"1.0.0","owner":"","createdOn":"2024-09-26T16:26:03Z","artifactType":"AVRO","globalId":1,"state":"ENABLED","groupId":"my-group","contentId":1,"artifactId":"share-price"}} ---- [role="_additional-resources"] diff --git a/docs/modules/ROOT/partials/getting-started/proc-installing-registry-operatorhub.adoc b/docs/modules/ROOT/partials/getting-started/proc-installing-registry-operatorhub.adoc index fdec567234..57e0ce7b49 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-installing-registry-operatorhub.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-installing-registry-operatorhub.adoc @@ -9,7 +9,7 @@ [role="_abstract"] You can install the {registry} Operator on your OpenShift cluster from the OperatorHub. The OperatorHub is available from the OpenShift Container Platform web console and provides an interface for cluster administrators to discover and install Operators. For more details, see link:{LinkOpenShiftIntroOperator}[{NameOpenShiftIntroOperator}]. -NOTE: You can install more than one instance of {registry} depending on your environment. The number of instances depends on the number and type of artifacts stored in {registry} and on your chosen storage option. +NOTE: You can install more than one replica of {registry} depending on your environment. The number of replicas depends on the number and type of artifacts stored in {registry} and on your chosen storage option. .Prerequisites diff --git a/docs/modules/ROOT/partials/getting-started/proc-installing-registry-sql-storage.adoc b/docs/modules/ROOT/partials/getting-started/proc-installing-registry-sql-storage.adoc index e369d0c3a6..f27b4e72bb 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-installing-registry-sql-storage.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-installing-registry-sql-storage.adoc @@ -25,33 +25,40 @@ For more details, see https://www.postgresql.org/docs/12/server-start.html + [source,bash] ---- -$ docker pull apicurio/apicurio-registry-sql:VERSION +$ docker pull apicurio/apicurio-registry:VERSION ---- + -`VERSION` is the {registry} release version, for example, `{registry-docker-version}`. For more details, see https://hub.docker.com/r/apicurio/apicurio-registry-sql/tags. +`VERSION` is the {registry} release version, for example, `{registry-docker-version}`. For more details, see https://hub.docker.com/r/apicurio/apicurio-registry/tags. -. Run the container image and specify the database connection URL and credentials for the PostgreSQL server as environment variables: +. Run the container image and specify the following environment variable for your Postgresql system: ++ +** `APICURIO_STORAGE_KIND` - The storage variant. Set this to `sql`. +** `APICURIO_STORAGE_SQL_KIND` - The type of SQL database to use. Set this to `postgresql` +** `APICURIO_DATASOURCE_URL` - The database connection URL. +** `APICURIO_DATASOURCE_USERNAME`, `APICURIO_DATASOURCE_PASSWORD` - The credentials for the PostgreSQL server. + [source,bash] ---- $ docker run -it -p 8080:8080 \ --e "REGISTRY_DATASOURCE_URL=jdbc:postgresql://postgres/apicurio-registry" \ --e "REGISTRY_DATASOURCE_USERNAME=apicurio-registry" \ --e "REGISTRY_DATASOURCE_PASSWORD=password" \ -apicurio/apicurio-registry-sql:VERSION +-e "APICURIO_STORAGE_KIND=sql" \ +-e "APICURIO_STORAGE_SQL_KIND=postgresql" \ +-e "APICURIO_DATASOURCE_URL=jdbc:postgresql://postgres/apicurio-registry" \ +-e "APICURIO_DATASOURCE_USERNAME=apicurio-registry" \ +-e "APICURIO_DATASOURCE_PASSWORD=password" \ +apicurio/apicurio-registry:VERSION ---- . Send a test request using the {registry} REST API. For example, enter the following `curl` command to create a simple Avro schema artifact for a share price application in the registry: + [source,bash] ---- -$ 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://localhost:8080/apis/registry/v2/groups/my-group/artifacts +$ curl -X POST -H "Content-type: application/json" --data '{"artifactId":"share-price","artifactType":"AVRO","name":"Share Price","labels":{"environment":"DEV","category":"finance"},"firstVersion":{"version":"1.0.0","content":{"content":"{\"type\":\"record\",\"name\":\"price\",\"namespace\":\"com.example\",\"fields\":[{\"name\":\"symbol\",\"type\":\"string\"},{\"name\":\"price\",\"type\":\"string\"}]}","contentType":"application/json"}}}' http://localhost:8080/apis/registry/v3/groups/my-group/artifacts ---- . Verify that the response includes the expected JSON body to confirm that the Avro schema artifact was created in the registry. For example: + [source,bash] ---- -{"name":"price","createdBy":"","createdOn":"2021-03-19T17:48:17+0000","modifiedOn":"2021-03-19T17:48:17+0000","id":"share-price","version":1,"type":"AVRO","globalId":12,"state":"ENABLED","groupId":"my-group","contentId":12} +{"artifact":{"name":"Share Price","owner":"","createdOn":"2024-09-26T16:26:03Z","modifiedBy":"","modifiedOn":"2024-09-26T16:26:03Z","artifactType":"AVRO","labels":{"environment":"DEV","category":"finance"},"groupId":"my-group","artifactId":"share-price"},"version":{"version":"1.0.0","owner":"","createdOn":"2024-09-26T16:26:03Z","artifactType":"AVRO","globalId":1,"state":"ENABLED","groupId":"my-group","contentId":1,"artifactId":"share-price"}} ---- [role="_additional-resources"] diff --git a/docs/modules/ROOT/partials/getting-started/proc-managing-artifact-references-using-rest-api.adoc b/docs/modules/ROOT/partials/getting-started/proc-managing-artifact-references-using-rest-api.adoc index 1861b14544..7567b1b50d 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-managing-artifact-references-using-rest-api.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-managing-artifact-references-using-rest-api.adoc @@ -15,7 +15,7 @@ The following artifact types support artifact references: * OpenAPI * AsyncAPI -This section shows a simple curl-based example of using the Core Registry API v2 to add and retrieve an artifact reference to a simple Avro schema artifact in {registry}. +This section shows a simple curl-based example of using the Core Registry API v3 to add and retrieve an artifact reference to a simple Avro schema artifact in {registry}. This example first creates a schema artifact named `ItemId`: @@ -48,37 +48,24 @@ This example then creates a schema artifact named `Item`, which includes a refer { "name":"itemId", "type":"com.example.common.ItemId" - }, + } ] } ---- .Prerequisites -ifdef::apicurio-registry,rh-service-registry[] * {registry} is installed and running in your environment. -endif::[] -ifdef::rh-openshift-sr[] -* You have a service account with the correct access permissions for {registry} instances. -* You have created an access token using your service account credentials. -* You have logged in to the {registry-url}[{registry} web console]. -endif::[] .Procedure -ifdef::rh-openshift-sr[] -. In the {registry} web console, for the {registry} instance that you want to connect to, select the options icon (three vertical dots) and click *Connection*. -. In the *Connection* page, copy the URL for the *Core Registry API* to a secure location. You will use this API endpoint to connect to the {registry} instance. -endif::[] - -. Add the `ItemId` schema artifact that you want to create the nested artifact reference to using the `/groups/\{group\}/artifacts` operation: +. Add the `ItemId` schema artifact that you want to create the nested artifact reference to using the `/groups/\{groupId\}/artifacts` operation: + [source,bash] ---- -$ curl -X POST MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts \ - -H "Content-Type: application/json; artifactType=AVRO" \ - -H "X-Registry-ArtifactId: ItemId" \ +$ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \ + -H "Content-Type: application/json" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ - --data '{"namespace": "com.example.common", "type": "record", "name": "ItemId", "fields":[{"name":"id", "type":"int"}]}' + --data '{"artifactId":"ItemId","artifactType":"AVRO","firstVersion":{"version":"1.0.0","content":{"content":"{\"namespace\":\"com.example.common\",\"name\":\"ItemId\",\"type\":\"record\",\"fields\":[{\"name\":\"id\",\"type\":\"int\"}]}","contentType":"application/json"}}}' ---- + * This example adds an Avro schema artifact with an artifact ID of `ItemId`. If you do not specify a unique artifact ID, {registry} generates one automatically as a UUID. @@ -89,37 +76,40 @@ endif::[] ifdef::rh-service-registry[] host name on which {registry} is deployed. For example: `my-cluster-service-registry-myproject.example.com`. endif::[] -ifdef::rh-openshift-sr[] -Core Registry API endpoint that you copied to connect to this {registry} instance. For example: `\https://service-registry.apps.app-sre-0.k3s7.p1.openshiftapps.com/t/f301375a-18a7-426c-bbd8-8e626a0a1d0e`. -endif::[] -* 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. +* 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. . Verify that the response includes the expected JSON body to confirm that the artifact was added. For example: + [source,bash] ---- -{"name":"ItemId","createdBy":"","createdOn":"2022-04-14T10:50:09+0000","modifiedBy":"","modifiedOn":"2022-04-14T10:50:09+0000","id":"ItemId","version":"1","type":"AVRO","globalId":1,"state":"ENABLED","groupId":"my-group","contentId":1,"references":[]} +{"artifact":{"owner":"","createdOn":"2024-09-26T16:27:38Z","modifiedBy":"","modifiedOn":"2024-09-26T16:27:38Z","artifactType":"AVRO","groupId":"my-group","artifactId":"ItemId"},"version":{"version":"1.0.0","owner":"","createdOn":"2024-09-26T16:27:38Z","artifactType":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2,"artifactId":"ItemId"}} ---- -. Add the `Item` schema artifact that includes the artifact reference to the `ItemId` schema using the `/groups/\{group\}/artifacts` operation: +. Add the `Item` schema artifact that includes the artifact reference to the `ItemId` schema using the `/groups/\{groupId\}/artifacts` operation: + [source,bash] ---- -$ curl -X POST MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts \ --H 'Content-Type: application/create.extended+json' \ --H "X-Registry-ArtifactId: Item" \ --H 'X-Registry-ArtifactType: AVRO' \ +$ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \ +-H 'Content-Type: application/json' \ -H "Authorization: Bearer $ACCESS_TOKEN" \ --data-raw '{ - "content": "{\r\n \"namespace\":\"com.example.common\",\r\n \"name\":\"Item\",\r\n \"type\":\"record\",\r\n \"fields\":[\r\n {\r\n \"name\":\"itemId\",\r\n \"type\":\"com.example.common.ItemId\"\r\n }\r\n ]\r\n}", - "references": [ - { - "groupId": "my-group", - "artifactId": "ItemId", - "name": "com.example.common.ItemId", - "version": "1" - } - ] + "artifactId": "Item", + "artifactType": "AVRO", + "firstVersion": { + "version": "1.0.0", + "content": { + "content": "{\"namespace\":\"com.example.common\",\"name\":\"Item\",\"type\":\"record\",\"fields\":[{\"name\":\"itemId\",\"type\":\"com.example.common.ItemId\"}]}", + "contentType": "application/json", + "references": [ + { + "name": "com.example.common.ItemId", + "groupId": "my-group", + "artifactId": "ItemId", + "version": "1.0.0" + } + ] + } + } }' ---- + @@ -129,28 +119,42 @@ $ curl -X POST MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts \ + [source,bash] ---- -{"name":"Item","createdBy":"","createdOn":"2022-04-14T11:52:15+0000","modifiedBy":"","modifiedOn":"2022-04-14T11:52:15+0000","id":"Item","version":"1","type":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2, "references":[{"artifactId":"ItemId","groupId":"my-group","name":"ItemId","version":"1"}] } +{"artifact":{"owner":"","createdOn":"2024-09-26T16:28:45Z","modifiedBy":"","modifiedOn":"2024-09-26T16:28:45Z","artifactType":"AVRO","groupId":"my-group","artifactId":"Item"},"version":{"version":"1.0.0","owner":"","createdOn":"2024-09-26T16:28:45Z","artifactType":"AVRO","globalId":3,"state":"ENABLED","groupId":"my-group","contentId":3,"artifactId":"Item"}} ---- -. Retrieve the artifact reference from {registry} by specifying the global ID of the artifact that includes the reference. In this example, the specified global ID is `2`: +. Retrieve the artifact reference from {registry} by specifying the coordinates of the artifact that includes the reference: + [source,bash] ---- -$ curl -H "Authorization: Bearer $ACCESS_TOKEN" MY-REGISTRY-URL/apis/registry/v2/ids/globalIds/2/references +$ curl -H "Authorization: Bearer $ACCESS_TOKEN" MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts/Item/versions/1.0.0/references ---- . Verify that the response includes the expected JSON body for this artifact reference. For example: + [source,bash] ---- -[{"groupId":"my-group","artifactId":"ItemId","version":"1","name":"com.example.common.ItemId"}] +[{"groupId":"my-group","artifactId":"ItemId","version":"1.0.0","name":"com.example.common.ItemId"}] ---- **Dereference** -There are some situations where having an artifact's content with the referenced content inlined might be helpful. For those situations, the Core Registry API v2 supports the _dereference parameter_ in certain operations. +There are some situations where having an artifact's content with the referenced content inlined might be helpful. For those situations, the Core Registry API v3 supports the _references parameter_ in certain operations. + +This support is currently implemented for Avro, JSON Schema, Protobuf, OpenAPI and AsyncAPI when the parameter is present in a particular API operation. The parameter is not supported in other schema types. -This support is currently implemented for Avro and Protobuf when the parameter is present in a particular API operation. The parameter is not supported in any other schema type. +. Retrieve the dereferenced (inlined) schema content: ++ +[source,bash] +---- +$ curl -H "Authorization: Bearer $ACCESS_TOKEN" MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts/Item/versions/1.0.0/content?references=DEREFERENCE +---- + +. Verify that the response includes the expected JSON body for this artifact content with the references inlined. For example: ++ +[source,bash] +---- +{"type":"record","name":"Item","namespace":"com.example.common","fields":[{"name":"itemId","type":{"type":"record","name":"ItemId","fields":[{"name":"id","type":"int"}]}}]} +---- #In Protobuf dereferencing content is only supported when all the schemas in the try belong to the same package.# @@ -158,4 +162,4 @@ This support is currently implemented for Avro and Protobuf when the parameter i [role="_additional-resources"] .Additional resources * For more details, see the {registry-rest-api}. -* For more examples of artifact references, see the section on configuring each artifact type in {registry-client-serdes-config}. \ No newline at end of file +* For more examples of artifact references, see the section on configuring each artifact type in {registry-client-serdes-config}. diff --git a/docs/modules/ROOT/partials/getting-started/proc-managing-artifact-versions-using-rest-api.adoc b/docs/modules/ROOT/partials/getting-started/proc-managing-artifact-versions-using-rest-api.adoc index 86b72bb83d..e7c2b0cf82 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-managing-artifact-versions-using-rest-api.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-managing-artifact-versions-using-rest-api.adoc @@ -5,39 +5,36 @@ = Managing schema and API artifact versions using {registry} REST API commands [role="_abstract"] -If you do not specify an artifact version when adding schema and API artifacts using the Core Registry API v2, {registry} generates a version automatically. The default version when creating a new artifact is `1`. +If you do not specify an artifact version number when adding schema and API artifacts using the Core Registry API v3, {registry} generates a version number automatically. The default version when creating a new artifact is `1`. -{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. +{registry} also supports custom versioning where you can specify a version number when creating the artifact or artifact version. Specifying a custom version value overrides the default version normally assigned when creating an artifact or artifact version. You can then use this version value when executing REST API operations that require a version number. -This section shows a simple curl-based example of using the Core Registry API v2 to add and retrieve a custom Apache Avro schema version in {registry}. You can specify custom versions to add or update artifacts, or to add artifact versions. +This section shows a simple curl-based example of using the Core Registry API v3 to add and retrieve a custom Apache Avro schema version in {registry}. You can specify custom version numbers to create artifacts, or to add artifact versions. .Prerequisites -ifdef::apicurio-registry,rh-service-registry[] * {registry} is installed and running in your environment. -endif::[] -ifdef::rh-openshift-sr[] -* You have a service account with the correct access permissions for {registry} instances. -* You have created an access token using your service account credentials. -* You have logged in to the {registry-url}[{registry} web console]. -endif::[] .Procedure -ifdef::rh-openshift-sr[] -. In the {registry} web console, for the {registry} instance that you want to connect to, select the options icon (three vertical dots) and click *Connection*. -. In the *Connection* page, copy the URL for the *Core Registry API* to a secure location. You will use this API endpoint to connect to the {registry} instance. -endif::[] -. 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: +. Add an artifact version in the registry using the `/groups/\{groupId\}/artifacts` operation. The following example `curl` command adds a simple artifact for a share price application: + [source,bash] ---- -$ curl -X POST -H "Content-Type: application/json; artifactType=AVRO" \ - -H "X-Registry-ArtifactId: my-share-price" -H "X-Registry-Version: 1.1.1" \ +$ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \ + -H "Content-Type: application/json" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ - --data '{"type":"record","name":" p","namespace":"com.example", \ - "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' \ - MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts + --data-raw '{ + "artifactId": "my-share-price", + "artifactType": "AVRO", + "firstVersion": { + "version": "1.1.1", + "content": { + "content": "{\"type\":\"record\",\"name\":\" p\",\"namespace\":\"com.example\", \"fields\":[{\"name\":\"symbol\",\"type\":\"string\"},{\"name\":\"price\",\"type\":\"string\"}]}", + "contentType": "application/json" + } + } +}' ---- + * 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, {registry} automatically generates a default version of `1`. @@ -48,28 +45,23 @@ endif::[] ifdef::rh-service-registry[] host name on which {registry} is deployed. For example: `my-cluster-service-registry-myproject.example.com`. endif::[] -ifdef::rh-openshift-sr[] -Core Registry API endpoint that you copied to connect to this {registry} instance. For example: `\https://service-registry.apps.app-sre-0.k3s7.p1.openshiftapps.com/t/f301375a-18a7-426c-bbd8-8e626a0a1d0e`. -endif::[] -* 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. +* 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. . Verify that the response includes the expected JSON body to confirm that the custom artifact version was added. For example: + [source,bash] ---- -{"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} +{"artifact":{"owner":"","createdOn":"2024-09-26T17:06:21Z","modifiedBy":"","modifiedOn":"2024-09-26T17:06:21Z","artifactType":"AVRO","groupId":"my-group","artifactId":"my-share-price"},"version":{"version":"1.1.1","owner":"","createdOn":"2024-09-26T17:06:21Z","artifactType":"AVRO","globalId":4,"state":"ENABLED","groupId":"my-group","contentId":4,"artifactId":"my-share-price"}} ---- * 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`. +* This was the fourth artifact added to the registry, so the global ID and content ID have a value of `4`. . 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`: + [source,bash] ---- $ curl -H "Authorization: Bearer $ACCESS_TOKEN" \ -MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts/my-share-price/versions/1.1.1 + MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts/my-share-price/versions/1.1.1/content {"type":"record","name":"price","namespace":"com.example", "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]} ---- diff --git a/docs/modules/ROOT/partials/getting-started/proc-managing-artifacts-using-client-code.adoc b/docs/modules/ROOT/partials/getting-started/proc-managing-artifacts-using-client-code.adoc deleted file mode 100644 index 3b2ff3e149..0000000000 --- a/docs/modules/ROOT/partials/getting-started/proc-managing-artifacts-using-client-code.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Metadata created by nebel -// ParentAssemblies: assemblies/getting-started/as_installing-the-registry.adoc - -[id="managing-artifacts-using-client-code_{context}"] -= Managing artifacts using a {registry} client application - -You can also manage artifacts stored in {registry} using a Java client application. You create, read, update, or delete artifacts stored in the registry using the {registry} Java client classes. - -.Prerequisites - -* See {registry-overview} -* You must have implemented a client application in Java that imports the {registry} client classes: `io.apicurio.registry.client.RegistryClient` -* {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: -+ -[source,java,subs="+quotes,attributes"] ----- -String registryUrl_node1 = PropertiesUtil.property(clientProperties, "apicurio.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> - "AVRO", - artifactId, - new ByteArrayInputStream(LogInput.SCHEMA$.toString().getBytes()) - ); - csa.toCompletableFuture().get(); - } - } ----- -<1> Configure the client application with the {registry} URL in the client properties. You must specify the {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. -ifdef::rh-service-registry[] -* For details on how to use the {registry} Kafka 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::[] diff --git a/docs/modules/ROOT/partials/getting-started/proc-managing-artifacts-using-rest-api.adoc b/docs/modules/ROOT/partials/getting-started/proc-managing-artifacts-using-rest-api.adoc index 86a9b01fe6..5c8ac5f1c1 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-managing-artifacts-using-rest-api.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-managing-artifacts-using-rest-api.adoc @@ -5,35 +5,31 @@ = Managing schema and API artifacts using {registry} REST API commands [role="_abstract"] -This section shows a simple curl-based example of using the Core Registry API v2 to add and retrieve a simple schema artifact in {registry}. +This section shows a simple curl-based example of using the Core Registry API v3 to add and retrieve a simple schema artifact in {registry}. .Prerequisites -ifdef::apicurio-registry,rh-service-registry[] * {registry} is installed and running in your environment. -endif::[] -ifdef::rh-openshift-sr[] -* You have a service account with the correct access permissions for {registry} instances. -* You have created an access token using your service account credentials. -* You have logged in to the {registry-url}[{registry} web console]. -endif::[] .Procedure -ifdef::rh-openshift-sr[] -. In the {registry} web console, for the {registry} instance that you want to connect to, select the options icon (three vertical dots) and click *Connection*. -. In the *Connection* page, copy the URL for the *Core Registry API* to a secure location. You will use this API endpoint to connect to the {registry} instance. -endif::[] -. Add an artifact to {registry} using the `/groups/\{group\}/artifacts` operation. The following example `curl` command adds a simple schema artifact for a share price application: +. Add an artifact to {registry} using the `/groups/\{groupId\}/artifacts` operation. The following example `curl` command adds a simple schema artifact for a share price application: + [source,bash] ---- -$ curl -X POST -H "Content-Type: application/json; artifactType=AVRO" \ - -H "X-Registry-ArtifactId: share-price" \ +$ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \ + -H "Content-Type: application/json" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ - --data '{"type":"record","name":"price","namespace":"com.example", \ - "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' \ - MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts + --data-raw '{ + "artifactId": "share-price", + "artifactType": "AVRO", + "firstVersion": { + "content": { + "content": "{\"type\":\"record\",\"name\":\" p\",\"namespace\":\"com.example\", \"fields\":[{\"name\":\"symbol\",\"type\":\"string\"},{\"name\":\"price\",\"type\":\"string\"}]}", + "contentType": "application/json" + } + } +}' ---- + * This example adds an Apache Avro schema artifact with an artifact ID of `share-price`. If you do not specify a unique artifact ID, {registry} generates one automatically as a UUID. @@ -44,28 +40,23 @@ endif::[] ifdef::rh-service-registry[] host name on which {registry} is deployed. For example: `my-cluster-service-registry-myproject.example.com`. endif::[] -ifdef::rh-openshift-sr[] -Core Registry API endpoint that you copied to connect to this {registry} instance. For example: `\https://service-registry.apps.app-sre-0.k3s7.p1.openshiftapps.com/t/f301375a-18a7-426c-bbd8-8e626a0a1d0e`. -endif::[] -* 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. +* 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. . Verify that the response includes the expected JSON body to confirm that the artifact was added. For example: + [source,bash] ---- -{"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} +{"artifact":{"owner":"","createdOn":"2024-09-26T17:24:21Z","modifiedBy":"","modifiedOn":"2024-09-26T17:24:21Z","artifactType":"AVRO","groupId":"my-group","artifactId":"share-price"},"version":{"version":"1","owner":"","createdOn":"2024-09-26T17:24:21Z","artifactType":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2,"artifactId":"share-price"}} ---- + * No version was specified when adding the artifact, so the default version `1` is created automatically. -* This was the second artifact added to {registry}, so the global ID and content ID have a value of `2`. -. Retrieve the artifact content from {registry} using its artifact ID in the API path. In this example, the specified ID is `share-price`: +* This was the second artifact added to {registry}, so the global ID and content ID have a value of `2`. +. Retrieve the artifact version content from {registry} using its artifact ID in the API path. In this example, the specified ID is `share-price`: + [source,bash] ---- $ curl -H "Authorization: Bearer $ACCESS_TOKEN" \ - MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts/share-price + MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts/share-price/versions/1/content {"type":"record","name":"price","namespace":"com.example", "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]} ---- diff --git a/docs/modules/ROOT/partials/getting-started/proc-migrating-registry-applications.adoc b/docs/modules/ROOT/partials/getting-started/proc-migrating-registry-applications.adoc index 5a5230ea3f..7f4da342b2 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-migrating-registry-applications.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-migrating-registry-applications.adoc @@ -23,7 +23,7 @@ You must review your existing {registry} client applications to ensure that the ---- -. In your Java client application, you must change your registry URL configuration, from pointing to the existing v2 API path to the new v3 path. Starting with v3, we use Vertx as the default platform for our rest client, due to this change, a RequestAdapter is required when the client is create. For example: +. In your Java client application, you must change your registry URL configuration, from pointing to the existing v2 API path to the new v3 path. Starting with v3, we use Vertx as the default platform for our rest client, due to this change, a RequestAdapter is required when the client is created. For example: + [source,java, subs="attributes+"] ---- @@ -43,7 +43,7 @@ ifdef::apicurio-registry[] {rest-client}. endif::[] ifdef::rh-service-registry[] -the link:{LinkServiceRegistryUser}#using-the-registry-client[{NameServiceRegistryUser}]. +the link:{LinkServiceRegistryUser}#using-the-registry-sdk[{NameServiceRegistryUser}]. endif::[] . If you are using the {registry} SerDes libraries, you must change the Maven dependencies, which have been repackaged in version 3.x. In {registry} {registry-v2}, the SerDes libraries were provided into three separate Maven modules, while this is still true, the names have been changed: @@ -76,7 +76,7 @@ _Existing registry v2 API path_: + [source,java] ---- -props.putIfAbsent(SerdeConfig.REGISTRY_URL, "http://new-registry.my-company.com/apis/registry/v2"); +props.putIfAbsent(SerdeConfig.REGISTRY_URL, "http://new-registry.my-company.com/apis/registry/v3"); ---- + _New registry v3 API path_: diff --git a/docs/modules/ROOT/partials/getting-started/proc-migrating-registry-data.adoc b/docs/modules/ROOT/partials/getting-started/proc-migrating-registry-data.adoc index 1a778a5c5e..43071c93f7 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-migrating-registry-data.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-migrating-registry-data.adoc @@ -5,51 +5,37 @@ = Migrating {registry} data [role="_abstract"] -Migrating data to {registry} 2.x requires exporting all data from your existing {registry-v1} deployment and importing it into the new 2.x deployment. If you are using {registry} as a schema registry for Kafka applications, data migration is critical because each Kafka message carries the global identifier for the schema stored in {registry}. This identifier must be preserved during registry data migration. +Migrating data to {registry} 3.x requires exporting all data from your existing {registry} 2.x deployment and importing it into the new 3.x deployment. If you are using {registry} as a schema registry for Kafka applications, data migration is critical because each Kafka message carries the global identifier for the schema stored in {registry}. This identifier must be preserved during registry data migration. -{registry} 2.x provides an API to bulk import/export all data from your registry deployment, which guarantees that all identifiers are kept when importing data from your existing registry. The export API downloads a custom `.zip` file containing all the information for your artifacts. The import API accepts this `.zip` and loads all artifacts into the registry in a single batch. +Both {registry} 3.x and 2.x provide an API to bulk import/export all data from your registry deployment, which guarantees that all identifiers are kept when importing data from your existing registry. The export API downloads a custom `.zip` file containing all the information for your artifacts. The import API accepts this `.zip` and loads all artifacts into the registry in a single batch. -{registry} {registry-v1} does not provide an import/export API. However, version 2.x provides an export tool compatible with {registry} {registry-v1} to export a `.zip`, which you can import into your 2.x registry. This tool uses common existing APIs to export all content in the registry. However, it is less performant than the 2.x export API, and should only be used when exporting from a {registry-v1} registry. +The {registry} 3.x import feature is able to import `.zip` contents created from either a 2.x or 3.x deployment. .Prerequisites -* Running {registry} instances of the {registry-v1} server you are exporting from and the 2.x server you are importing into. -* Download the -ifdef::apicurio-registry[] -link:https://github.com/Apicurio/apicurio-registry/releases/download/{registry-release}/apicurio-registry-utils-exportV1-{registry-release}.jar[{registry} exportV1 tool] from GitHub. -endif::[] -ifdef::rh-service-registry[] -link:{download-url-registry-distribution}[{registry} exportV1 tool] from the Red Hat Customer Portal. -endif::[] -This is a Java application that you can run on the command line. +* Running a {registry} instance of the 2.x server you are exporting from and the 3.x instance you are importing into. .Procedure -. Export all the data from {registry} {registry-v1} using the `exportV1` tool. This generates a `registry-export.zip` file in your current directory: -+ -[source,bash, subs="attributes+"] ----- -java -jar apicurio-registry-utils-exportV1-{registry-release}.jar http://old-registry.my-company.com/api ----- - -. Import the `.zip` file into {registry} 2.x using the import API: +. Export all the data from {registry} 2.x using the Export feature, which can be accessed from the UI or the REST API. This generates a `all-artifacts.zip` file in a directory of your choice. +. Import the `.zip` file into {registry} 3.x using the import API: + [source,bash, subs="attributes+"] ---- -curl -X POST "http://new-registry.my-company.com/apis/registry/v2/admin/import" \ +curl -X POST "http://new-registry.my-company.com/apis/registry/v3/admin/import" \ -H "Accept: application/json" -H "Content-Type: application/zip" \ - --data-binary @registry-export.zip + --data-binary @all-artifacts.zip ---- -. Check that all the artifacts have been imported into the new 2.x registry by running these commands and comparing the count field: +. Check that all the artifacts have been imported into the new 3.x registry by running these commands and comparing the count field: + [source,bash, subs="attributes+"] ---- -curl "http://old-registry.my-company.com/api/search/artifacts" +curl "http://old-registry.my-company.com/apis/registry/v2/search/artifacts" ---- + [source,bash, subs="attributes+"] ---- -curl "http://new-registry.my-company.com/apis/registry/v2/search/artifacts" +curl "http://new-registry.my-company.com/apis/registry/v3/search/artifacts" ---- [role="_additional-resources"] @@ -61,4 +47,3 @@ endif::[] ifdef::rh-service-registry[] the link:{LinkServiceRegistryUser}#exporting-importing-using-rest-api[{NameServiceRegistryUser}]. endif::[] -* For more details on the export tool for migrating from version 1.x to 2.x, see the link:https://github.com/Apicurio/apicurio-registry/tree/2.2.x/utils/exportV1[Apicurio Registry export utility for 1.x versions]. diff --git a/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-config-consumer.adoc b/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-config-consumer.adoc index b6ef07e67b..9721d2b714 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-config-consumer.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-config-consumer.adoc @@ -18,7 +18,7 @@ This procedure describes how to configure a Kafka consumer client written in Jav + [source,java,subs="+quotes,attributes"] ---- -String registryUrl = "https://registry.example.com/apis/registry/v2"; +String registryUrl = "https://registry.example.com/apis/registry/v3"; Properties props = new Properties(); props.putIfAbsent(SerdeConfig.REGISTRY_URL, registryUrl); ---- diff --git a/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-config-producer.adoc b/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-config-producer.adoc index 3ef75a4940..772084f297 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-config-producer.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-config-producer.adoc @@ -18,7 +18,7 @@ This procedure describes how to configure a Kafka producer client written in Jav + [source,java,subs="+quotes,attributes"] ---- -String registryUrl = "https://registry.example.com/apis/registry/v2"; +String registryUrl = "https://registry.example.com/apis/registry/v3"; Properties props = new Properties(); props.putIfAbsent(SerdeConfig.REGISTRY_URL, registryUrl); ---- diff --git a/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-config-stream.adoc b/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-config-stream.adoc index 55ea83bf06..c6ecd05e07 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-config-stream.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-config-stream.adoc @@ -18,7 +18,7 @@ This procedure describes how to configure a Kafka Streams client written in Java + [source,java,subs="+quotes,attributes"] ---- -String registryUrl = "https://registry.example.com/apis/registry/v2"; +String registryUrl = "https://registry.example.com/apis/registry/v3"; RegistryService client = RegistryClient.cached(registryUrl); ---- diff --git a/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-register.adoc b/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-register.adoc index 5942eb90a6..6d880f60ea 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-register.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-register.adoc @@ -42,7 +42,7 @@ endif::[] "namespace":"com.example", "fields":[{"name":"symbol","type":"string"}, {"name":"price","type":"string"}]}' - https://my-cluster-my-registry-my-project.example.com/apis/registry/v2/groups/my-group/artifacts -s <2> + https://my-cluster-my-registry-my-project.example.com/apis/registry/v3/groups/my-group/artifacts -s <2> ---- <1> Simple Avro schema artifact. <2> OpenShift route name that exposes {registry}. @@ -63,7 +63,7 @@ endif::[] register <1> - http://REGISTRY-URL/apis/registry/v2 <2> + http://REGISTRY-URL/apis/registry/v3 <2> TestGroup <3> @@ -86,7 +86,7 @@ endif::[] ---- <1> Specify `register` as the execution goal to upload the schema artifact to the registry. -<2> Specify the {registry} URL with the `../apis/registry/v2` endpoint. +<2> Specify the {registry} URL with the `../apis/registry/v3` endpoint. <3> Specify the {registry} artifact group ID. <4> You can upload multiple artifacts using the specified group ID, artifact ID, and location. @@ -96,7 +96,7 @@ endif::[] [source,java,subs="+quotes,attributes"] ---- String registryUrl_node1 = PropertiesUtil.property(clientProperties, "apicurio.url.node1", - "https://my-cluster-service-registry-myproject.example.com/apis/registry/v2"); <1> + "https://my-cluster-service-registry-myproject.example.com/apis/registry/v3"); <1> try (RegistryService service = RegistryClient.create(registryUrl_node1)) { String artifactId = ApplicationImpl.INPUT_TOPIC + "-value"; try { diff --git a/docs/modules/ROOT/partials/getting-started/proc-testing-artifacts-using-maven-plugin.adoc b/docs/modules/ROOT/partials/getting-started/proc-testing-artifacts-using-maven-plugin.adoc index 43dff16382..1a1bcc0b27 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-testing-artifacts-using-maven-plugin.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-testing-artifacts-using-maven-plugin.adoc @@ -29,7 +29,7 @@ NOTE: When testing artifacts using the Maven plug-in, even if the artifact passe test-update <1> - MY-REGISTRY-URL/apis/registry/v2 <2> + MY-REGISTRY-URL/apis/registry/v3 <2> MY-AUTH-SERVER MY-CLIENT-ID MY-CLIENT-SECRET <3> @@ -48,13 +48,8 @@ NOTE: When testing artifacts using the Maven plug-in, even if the artifact passe ---- + <1> Specify `test-update` as the execution goal to test the schema artifact. -<2> Specify the {registry} URL with the `../apis/registry/v2` endpoint. -ifdef::apicurio-registry,rh-service-registry[] +<2> Specify the {registry} URL with the `../apis/registry/v3` endpoint. <3> If authentication is required, you can specify your authentication server and client credentials. -endif::[] -ifdef::rh-openshift-sr[] -<3> Specify your service account ID and secret and the {org-name} Single Sign-On authentication server: `{sso-token-url}` -endif::[] <4> Specify the {registry} artifact group ID. You can specify the `default` group if you do not want to use a unique group. <5> You can test multiple artifacts from a specified directory using the artifact ID. diff --git a/docs/modules/ROOT/partials/getting-started/proc-writing-registry-client.adoc b/docs/modules/ROOT/partials/getting-started/proc-writing-registry-sdk.adoc similarity index 81% rename from docs/modules/ROOT/partials/getting-started/proc-writing-registry-client.adoc rename to docs/modules/ROOT/partials/getting-started/proc-writing-registry-sdk.adoc index 73ff0e9b65..01bb8f215e 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-writing-registry-client.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-writing-registry-sdk.adoc @@ -1,20 +1,17 @@ // Metadata created by nebel // ParentAssemblies: assemblies/getting-started/as_installing-the-registry.adoc -[id="writing-registry-client_{context}"] -= Writing {registry} Java client applications +[id="writing-registry-sdk_{context}"] += Writing {registry} SDK applications [role="_abstract"] -You can write a Java client application to manage artifacts stored in {registry} by using the {registry} Java client classes. +You can write a client application to manage artifacts stored in {registry} by using one of the {registry} SDKs. + +== Using the {registry} Java SDK .Prerequisites -ifdef::apicurio-registry,rh-service-registry[] * {registry} is installed and running in your environment. -endif::[] * You have created a Maven project for your Java client application. For more details, see https://maven.apache.org/index.html[Apache Maven]. -ifdef::rh-openshift-sr[] -* You have a service account with the correct access permissions for {registry} instances. -endif::[] .Procedure . Add the following dependency to your Maven project: @@ -36,7 +33,7 @@ public class ClientExample { public static void main(String[] args) throws Exception { // Create a registry client - String registryUrl = "https://my-registry.my-domain.com/apis/registry/v2"; <1> + String registryUrl = "https://my-registry.my-domain.com/apis/registry/v3"; <1> VertXRequestAdapter vertXRequestAdapter = new VertXRequestAdapter(VertXAuthFactory.defaultVertx); vertXRequestAdapter.setBaseUrl(REGISTRY_URL); @@ -45,7 +42,7 @@ public class ClientExample { } ---- + -<1> If you specify an example {registry} URL of `\https://my-registry.my-domain.com`, the client will automatically append `/apis/registry/v2`. +<1> If you specify an example {registry} URL of `\https://my-registry.my-domain.com`, the client will automatically append `/apis/registry/v3`. <2> For more options when creating a {registry} client, see the Java client configuration in the next section. When the client is created, you can use all of the operations available in the {registry} REST API in the client. For more details, see the {registry-rest-api}. @@ -55,3 +52,15 @@ When the client is created, you can use all of the operations available in the { * For an open source example of how to use and customize the {registry} client, see the https://github.com/Apicurio/apicurio-registry/tree/main/examples[Apicurio Registry REST client demonstration]. * For details on how to use the {registry} Kafka client serializers/deserializers (SerDes) in producer and consumer applications, see {kafka-client-serdes}. + +== Using the {registry} Typescript SDK + +TBD + +== Using the {registry} Python SDK + +TBD + +== Using the {registry} Golang SDK + +TBD diff --git a/docs/modules/ROOT/partials/getting-started/ref-registry-artifact-metadata.adoc b/docs/modules/ROOT/partials/getting-started/ref-registry-artifact-metadata.adoc index 7c09ed9cf3..48de645ed6 100644 --- a/docs/modules/ROOT/partials/getting-started/ref-registry-artifact-metadata.adoc +++ b/docs/modules/ROOT/partials/getting-started/ref-registry-artifact-metadata.adoc @@ -4,7 +4,7 @@ = {registry} artifact metadata [role="_abstract"] -When an artifact is added to {registry}, a set of metadata properties is created and stored along with the artifact content. This metadata consists of system-generated or user-generated properties that are read-only, and editable properties that you can update after the artifact is created. +When an artifact is added to {registry}, a set of metadata properties is created and stored. This metadata consists of system-generated or user-generated properties that are read-only, and editable properties that you can update after the artifact is created. .{registry} system-generated metadata [.table-expandable,width="100%",cols="1,1,2",options="header"] @@ -12,12 +12,6 @@ When an artifact is added to {registry}, a set of metadata properties is created |Property |Type |Description -|`contentId` -|integer -|Unique identifier of artifact content in {registry}. The same content ID can be shared by multiple artifact versions when artifact versions have identical content. For example, a content ID of `4` can be used by multiple artifact versions with the same content. -|`createdBy` -|string -|The name of the user who created the artifact. |`createdOn` |date |The date and time when the artifact was created, for example, `2023-10-11T14:15:28Z`. @@ -30,9 +24,6 @@ When an artifact is added to {registry}, a set of metadata properties is created |`modifiedOn` |date |The date and time at which the artifact was modified, for example, `2023-10-11T14:15:28Z`. -|`type` -|ArtifactType -|The supported artifact type, for example, `AVRO`, `OPENAPI`, or `PROTOBUF`. |=== @@ -45,15 +36,12 @@ When an artifact is added to {registry}, a set of metadata properties is created |`groupId` |string |Unique identifier of an artifact group in {registry}, for example, `development` or `production`. When creating an artifact by using the {registry} web console, if you do not provide a group ID, this is set to `default`. You must provide a group ID when using the Apicurio Registry REST API, Java client, or Maven plug-in. -|`id` +|`artifactId` |string -|Unique identifier of an artifact in {registry}. You can provide an artifact ID or use the UUID generated by {registry}, for example, `8d168cad-1865-4e6c-bb7e-04e8be005bea`. Different versions of an artifact use the same artifact ID, but have different global IDs. -|`references` -|array of ArtifactReference -|Optional set of artifact references contained in the artifact, which you can provide when creating the artifact. The following simple example shows a single artifact reference: `[{"groupId":"my-group","artifactId":"ItemId","version":"1","name":"com.example.common.ItemId"}]`. -|`version` -|integer -|The latest version of the artifact. You can use the generated version, for example, `3`, or provide a version by using the {registry} REST API or Maven plug-in, for example, `2.1.6`. +|Unique identifier of an artifact in {registry}. You can provide an artifact ID or use the UUID generated by {registry}, for example, `8d168cad-1865-4e6c-bb7e-04e8be005bea`. Different versions of an artifact use the same artifact ID, but have different global IDs. +|`artifactType` +|ArtifactType +|The supported artifact type, for example, `AVRO`, `OPENAPI`, or `PROTOBUF`. |=== @@ -63,27 +51,23 @@ When an artifact is added to {registry}, a set of metadata properties is created |Property |Type |Description +|`name` +|string +|Optional human-readable name of the artifact, for example, `My first Avro schema`. |`description` |string -|Optional meaningful description of the artifact, for example, `This is a simple OpenAPI for testing`. You can provide a description, or it can be automatically discovered from the `info` section of OpenAPI and AsyncAPI artifacts, if already provided. +|Optional meaningful description of the artifact, for example, `This is a simple OpenAPI for testing`. |`labels` -|array of string -|Optional comma-separated list of labels used to filter and search for the artifact, for example, `test,protobuf`. Provided by the user. -|`name` -|string -|Optional human-readable name of the artifact, for example, `My first Avro schema`. You can provide a description, or it can be automatically discovered from the `info` section of OpenAPI and AsyncAPI artifacts, if the `title` field has a value. -|`properties` | map |Optional list of user-defined name-value pairs associated with the artifact. The name and value must be strings, for example, `my-key` and `my-value`. -|`state` -|ArtifactState -|The latest state of the artifact: `ENABLED`, `DISABLED`, or `DEPRECATED`. Defaults to `ENABLED`. +|`owner` +|string +|The name of the user who owns the artifact. |=== .Updating artifact metadata * You can use the {registry} REST API or web console to update the set of editable metadata properties. -* You can update the `state` property only by using the {registry} REST API. [role="_additional-resources"] .Additional resources -For more details, see the `/artifacts/\{artifactId\}/meta` endpoint in the {registry-rest-api}. +For more details, see the `/groups/\{groupId\}/artifacts/\{artifactId\}` endpoint in the {registry-rest-api}. diff --git a/docs/modules/ROOT/partials/getting-started/ref-registry-artifact-states.adoc b/docs/modules/ROOT/partials/getting-started/ref-registry-artifact-states.adoc index 4d37d88481..08c839c8b0 100644 --- a/docs/modules/ROOT/partials/getting-started/ref-registry-artifact-states.adoc +++ b/docs/modules/ROOT/partials/getting-started/ref-registry-artifact-states.adoc @@ -3,12 +3,12 @@ [id="registry-artifact-states_{context}"] -= {registry} artifact states += {registry} artifact version states [role="_abstract"] -The valid artifact states in {registry} are `ENABLED`, `DISABLED`, and `DEPRECATED`. +The valid artifact version states in {registry} are `ENABLED`, `DISABLED`, and `DEPRECATED`. -.{registry} artifact states +.{registry} artifact version states [%header,cols=2*] |=== |State @@ -16,7 +16,7 @@ The valid artifact states in {registry} are `ENABLED`, `DISABLED`, and `DEPRECAT |`ENABLED` |Basic state, all the operations are available. |`DISABLED` -|The artifact and its metadata is viewable and searchable using the {registry} web console, but its content cannot be fetched by any client. +|The artifact version metadata is viewable and searchable using the {registry} web console, but its content cannot be fetched by any client. |`DEPRECATED` -|The artifact is fully usable but a header is added to the REST API response whenever the artifact content is fetched. The {registry} Rest Client will also log a warning whenever it sees deprecated content. +|The artifact version is fully usable but a header is added to the REST API response whenever the artifact version content is fetched. |=== diff --git a/docs/modules/ROOT/partials/getting-started/ref-registry-artifact-version-metadata.adoc b/docs/modules/ROOT/partials/getting-started/ref-registry-artifact-version-metadata.adoc new file mode 100644 index 0000000000..c2fd14c542 --- /dev/null +++ b/docs/modules/ROOT/partials/getting-started/ref-registry-artifact-version-metadata.adoc @@ -0,0 +1,80 @@ +// Metadata created by nebel + +[id="registry-artifact-version-metadata_{context}"] += {registry} artifact version metadata + +[role="_abstract"] +When an artifact version is added to a {registry} artifact, a set of metadata properties is created and stored along with the artifact version content. This metadata consists of system-generated or user-generated properties that are read-only, and editable properties that you can update after the artifact version is created. + +.{registry} system-generated metadata +[.table-expandable,width="100%",cols="1,1,2",options="header"] +|=== +|Property +|Type +|Description +|`owner` +|string +|The name of the user who created the artifact version. +|`createdOn` +|date +|The date and time when the artifact version was created, for example, `2023-10-11T14:15:28Z`. +|`modifiedBy` +|string +|The user who modified the artifact version. +|`modifiedOn` +|date +|The date and time at which the artifact version was modified, for example, `2023-10-11T14:15:28Z`. +|`contentId` +|integer +|Unique identifier of artifact version content in {registry}. The same content ID can be shared by multiple artifact versions when artifact versions have identical content. For example, a content ID of `4` can be used by multiple artifact versions with the same content, even across multiple artifacts. +|`globalId` +|integer +|Globally unique identifier of an artifact version in {registry}. For example, a global ID of `1` is assigned to the first artifact version created in {registry}. +|=== + + +.{registry} user-provided or system-generated metadata +[.table-expandable,width="100%",cols="1,1,2",options="header"] +|=== +|Property +|Type +|Description +|`groupId` +|string +|Unique identifier of an artifact group in {registry}, for example, `development` or `production`. +|`artifactId` +|string +|Unique identifier of an artifact in {registry}. +|`version` +|integer +|The version string of the artifact version. If not provided, the system will generate a new sequential version. You can provide a version when using the {registry} REST API, SDKs, or Maven plug-in, for example, `2.1.6`. +|=== + + +.{registry} editable metadata +[.table-expandable,width="100%",cols="1,1,2",options="header"] +|=== +|Property +|Type +|Description +|`name` +|string +|Optional human-readable name of the artifact version, for example, `Version One`. +|`description` +|string +|Optional meaningful description of the artifact version, for example, `This is the first version for testing`. +|`labels` +| map +|Optional list of user-defined name-value pairs associated with the artifact version. The name and value must be strings, for example, `my-key` and `my-value`. +|`state` +|ArtifactState +|The state of the artifact version: `ENABLED`, `DISABLED`, or `DEPRECATED`. Defaults to `ENABLED`. +|=== + +.Updating artifact version metadata +* You can use the {registry} REST API or web console to update the set of editable metadata properties. +* You can update the `state` property only by using the {registry} REST API. + +[role="_additional-resources"] +.Additional resources +For more details, see the `/groups/\{groupId\}/artifacts/\{artifactId\}/versions/\{versionId\}` endpoint in the {registry-rest-api}. diff --git a/docs/modules/ROOT/partials/getting-started/ref-registry-group-metadata.adoc b/docs/modules/ROOT/partials/getting-started/ref-registry-group-metadata.adoc new file mode 100644 index 0000000000..bff563a29e --- /dev/null +++ b/docs/modules/ROOT/partials/getting-started/ref-registry-group-metadata.adoc @@ -0,0 +1,62 @@ +// Metadata created by nebel + +[id="registry-group-metadata_{context}"] += {registry} group metadata + +[role="_abstract"] +When a group is created in {registry}, a set of metadata properties is created and stored. This metadata consists of system-generated or user-generated properties that are read-only, and editable properties that you can update after the group is created. + +.{registry} system-generated metadata +[.table-expandable,width="100%",cols="1,1,2",options="header"] +|=== +|Property +|Type +|Description +|`owner` +|string +|The name of the user who created the group. +|`createdOn` +|date +|The date and time when the group was created, for example, `2023-10-11T14:15:28Z`. +|`modifiedBy` +|string +|The name of the user who modified the group. +|`modifiedOn` +|date +|The date and time at which the group was modified, for example, `2023-10-11T14:15:28Z`. +|=== + + +.{registry} user-provided or system-generated metadata +[.table-expandable,width="100%",cols="1,1,2",options="header"] +|=== +|Property +|Type +|Description +|`groupId` +|string +|Unique identifier of the artifact group in {registry}, for example, `development` or `production`. +|=== + + +.{registry} editable metadata +[.table-expandable,width="100%",cols="1,1,2",options="header"] +|=== +|Property +|Type +|Description +|`description` +|string +|Optional meaningful description of the group, for example, `This is a simple group for testing`. +|`labels` +| map +|Optional list of user-defined name-value pairs associated with the group. The name and value must be strings, for example, `my-key` and `my-value`. +|=== + +.Updating group metadata +* You can use the {registry} REST API or web console to update the set of editable metadata properties. +* You can update the `state` property only by using the {registry} REST API. + +[role="_additional-resources"] +.Additional resources +For more details, see the `/groups/\{groupId\}` endpoint in the {registry-rest-api}. diff --git a/docs/modules/ROOT/partials/getting-started/ref-registry-kafka-topic-names.adoc b/docs/modules/ROOT/partials/getting-started/ref-registry-kafka-topic-names.adoc index 12833ed24b..aa5fa04ffd 100644 --- a/docs/modules/ROOT/partials/getting-started/ref-registry-kafka-topic-names.adoc +++ b/docs/modules/ROOT/partials/getting-started/ref-registry-kafka-topic-names.adoc @@ -13,10 +13,10 @@ The default Kafka topic name that {registry} uses to store data is `kafkasql-jou |Environment variable |Java system property |Default value -| `REGISTRY_KAFKASQL_TOPIC` +| `APICURIO_KAFKASQL_TOPIC` | `apicurio.kafkasql.topic` | `kafkasql-journal` -| `REGISTRY_KAFKASQL_TOPIC_AUTO_CREATE` +| `APICURIO_KAFKASQL_TOPIC_AUTO_CREATE` | `apicurio.kafkasql.topic.auto-create` | `true` |=== diff --git a/docs/modules/ROOT/partials/getting-started/ref-registry-client.adoc b/docs/modules/ROOT/partials/getting-started/ref-registry-sdk.adoc similarity index 86% rename from docs/modules/ROOT/partials/getting-started/ref-registry-client.adoc rename to docs/modules/ROOT/partials/getting-started/ref-registry-sdk.adoc index 0f7567bd7c..c5828a02ab 100644 --- a/docs/modules/ROOT/partials/getting-started/ref-registry-client.adoc +++ b/docs/modules/ROOT/partials/getting-started/ref-registry-sdk.adoc @@ -1,8 +1,8 @@ // Metadata created by nebel -// ParentAssemblies: assemblies/getting-started/assembly-using-the-registry-client.adoc +// ParentAssemblies: assemblies/getting-started/assembly-using-the-registry-sdk.adoc -[id="registry-client-config_{context}"] -= {registry} Java client configuration +[id="registry-sdk-config_{context}"] += {registry} Java SDK configuration [role="_abstract"] The {registry} Java client includes the following configuration options, based on the client factory: @@ -14,7 +14,7 @@ The {registry} Java client includes the following configuration options, based o |Description |Arguments |Plain client -|Basic REST client used to interact with a running {registry} instance. +|Basic REST client used to interact with a running {registry}. |`baseUrl` |Client with custom configuration |{registry} client using the configuration provided by the user. @@ -22,9 +22,6 @@ The {registry} Java client includes the following configuration options, based o |Client with custom configuration and authentication |{registry} client that accepts a map containing custom configuration. For example, this is useful to add custom headers to the calls. You must also provide an authentication server to authenticate the requests. -ifdef::rh-openshift-sr[] -The {org-name} Single Sign-On authentication server is `{sso-token-url}`. -endif::[] |`baseUrl, Map configs, Auth auth` |=== diff --git a/docs/modules/ROOT/partials/getting-started/ref-registry-security-configuration.adoc b/docs/modules/ROOT/partials/getting-started/ref-registry-security-configuration.adoc index 9be84f94ce..3fb33467c0 100644 --- a/docs/modules/ROOT/partials/getting-started/ref-registry-security-configuration.adoc +++ b/docs/modules/ROOT/partials/getting-started/ref-registry-security-configuration.adoc @@ -144,15 +144,15 @@ To enable using roles assigned by {keycloak}, set the following environment vari | When set to `token`, user roles are taken from the authentication token. |String |`token` -|`REGISTRY_AUTH_ROLES_ADMIN` +|`APICURIO_AUTH_ROLES_ADMIN` |The name of the role that indicates a user is an admin. |String |`sr-admin` -|`REGISTRY_AUTH_ROLES_DEVELOPER` +|`APICURIO_AUTH_ROLES_DEVELOPER` |The name of the role that indicates a user is a developer. |String |`sr-developer` -|`REGISTRY_AUTH_ROLES_READONLY` +|`APICURIO_AUTH_ROLES_READONLY` |The name of the role that indicates a user has read-only access. |String |`sr-readonly` @@ -223,27 +223,27 @@ Because there are no default admin users in {registry}, it is usually helpful to |Description |Type |Default -|`REGISTRY_AUTH_ADMIN_OVERRIDE_ENABLED` +|`APICURIO_AUTH_ADMIN_OVERRIDE_ENABLED` | Enables the admin-override feature. |String |`false` -|`REGISTRY_AUTH_ADMIN_OVERRIDE_FROM` +|`APICURIO_AUTH_ADMIN_OVERRIDE_FROM` |Where to look for admin-override information. Only `token` is currently supported. |String |`token` -|`REGISTRY_AUTH_ADMIN_OVERRIDE_TYPE` +|`APICURIO_AUTH_ADMIN_OVERRIDE_TYPE` |The type of information used to determine if a user is an admin. Values depend on the value of the FROM variable, for example, `role` or `claim` when FROM is `token`. |String |`role` -|`REGISTRY_AUTH_ADMIN_OVERRIDE_ROLE` +|`APICURIO_AUTH_ADMIN_OVERRIDE_ROLE` |The name of the role that indicates a user is an admin. |String |`sr-admin` -|`REGISTRY_AUTH_ADMIN_OVERRIDE_CLAIM` +|`APICURIO_AUTH_ADMIN_OVERRIDE_CLAIM` |The name of a JWT token claim to use for determining admin-override. |String |`org-admin` -|`REGISTRY_AUTH_ADMIN_OVERRIDE_CLAIM_VALUE` +|`APICURIO_AUTH_ADMIN_OVERRIDE_CLAIM_VALUE` |The value that the JWT token claim indicated by the CLAIM variable must be for the user to be granted admin-override. |String |`true` @@ -272,12 +272,12 @@ You can set the following options to `true` to enable owner-only authorization f |Boolean |`false` -|`REGISTRY_AUTH_OBAC_ENABLED` +|`APICURIO_AUTH_OBAC_ENABLED` |`apicurio.auth.owner-only-authorization` |Boolean |`false` -|`REGISTRY_AUTH_OBAC_LIMIT_GROUP_ACCESS` +|`APICURIO_AUTH_OBAC_LIMIT_GROUP_ACCESS` |`apicurio.auth.owner-only-authorization.limit-group-access` |Boolean |`false` @@ -306,7 +306,7 @@ To enable authenticated read access, you must first enable role-based authorizat |`registry.auth.enabled` |Boolean |`false` -|`REGISTRY_AUTH_AUTHENTICATED_READS_ENABLED` +|`APICURIO_AUTH_AUTHENTICATED_READS_ENABLED` |`apicurio.auth.authenticated-read-access.enabled` |Boolean |`false` @@ -335,7 +335,7 @@ calls to the REST API, set the following options to `true`: |`registry.auth.enabled` |Boolean |`false` -|`REGISTRY_AUTH_ANONYMOUS_READ_ACCESS_ENABLED` +|`APICURIO_AUTH_ANONYMOUS_READ_ACCESS_ENABLED` |`apicurio.auth.anonymous-read-access.enabled` |Boolean |`false` diff --git a/docs/modules/ROOT/partials/shared/attributes.adoc b/docs/modules/ROOT/partials/shared/attributes.adoc index cfb35c01e0..864ecae134 100644 --- a/docs/modules/ROOT/partials/shared/attributes.adoc +++ b/docs/modules/ROOT/partials/shared/attributes.adoc @@ -74,7 +74,7 @@ endif::[] :attachmentsdir: files :registry-ocp-version: 4.14 :registry-db-version: 15 -:registry-url: \http://MY_REGISTRY_URL/ui +:registry-url: \http://MY_REGISTRY_UI_URL/ //integration products :amq-version: 2.5 @@ -108,7 +108,7 @@ include::attributes-links.adoc[] :managing-registry-artifacts-ui: xref:managing-registry-artifacts-ui_{context}[] :managing-registry-artifacts-api: xref:managing-registry-artifacts-api_{context}[] :managing-registry-artifacts-maven: xref:managing-registry-artifacts-maven_{context}[] -:rest-client: xref:using-the-registry-client_{context}[] +:rest-client: xref:using-the-registry-sdk_{context}[] :kafka-client-serdes: xref:using-kafka-client-serdes_{context}[] :registry-client-serdes-config: xref:configuring-kafka-client-serdes_{context}[] :registry-rest-api: link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation] diff --git a/docs/readme.adoc b/docs/readme.adoc index 38abb13bb9..252081da9c 100644 --- a/docs/readme.adoc +++ b/docs/readme.adoc @@ -2,7 +2,7 @@ The Apicurio Registry user documentation is created using AsciiDoc (https://asciidoc.org/). This readme describes the user documentation conventions and directory structure, and explains how to build the documentation using the Antora site generator (https://antora.org/). -== How the documentation is orgainized +== How the documentation is organized The Apicurio Registry user documentation is organized for delivering flexible content, which is a framework for putting together exactly the content you need, and making it easier to reuse the same content in multiple places. This framework includes the following building blocks: diff --git a/docs/rest-api/src/main/assembly/static-assembly.xml b/docs/rest-api/src/main/assembly/static-assembly.xml index b41c3df188..26d4ed2fd0 100644 --- a/docs/rest-api/src/main/assembly/static-assembly.xml +++ b/docs/rest-api/src/main/assembly/static-assembly.xml @@ -9,7 +9,7 @@ false - ${basedir}/../../app/src/main/resources-unfiltered/META-INF/resources/api-specifications/registry/v2/openapi.json + ${basedir}/../../app/src/main/resources-unfiltered/META-INF/resources/api-specifications/registry/v3/openapi.json openapi.json