Clarify groups, add new versioning and export/import docs (#1438)

* add clarification from eric on optional groups, tidy up ui labels

* properly modularize maven plugin docs

* new topics on using rest api to manage custom versions and export/import registry data, tidy up

docs/modules/ROOT/pages/getting-started/assembly-configuring-the-registry.adoc

@@ -4,6 +4,7 @@ include::{mod-loc}shared/all-attributes.adoc[]
 [id="configuring-the-registry"]
 = Configuring your {registry} deployment
 
+[role="_abstract"]
 This chapter explains various configuration options for {registry}, such as authentication settings, logging, and health checks on OpenShift.
 
 * xref:registry-security[]

docs/modules/ROOT/pages/getting-started/assembly-installing-registry-openshift.adoc

@@ -4,6 +4,7 @@ include::{mod-loc}shared/all-attributes.adoc[]
 [id="installing-registry-ocp"]
 = Installing {registry} on OpenShift
 
+[role="_abstract"]
 This chapter explains how to install {registry}:
 
 * xref:installing-registry-operatorhub[]
@@ -15,6 +16,7 @@ This chapter explains how to install {registry}:
 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.
 
 ifdef::apicurio-registry[]
+[role="_additional-resources"]
 .Additional resources
 * For details on building from source, see https://github.com/Apicurio/apicurio-registry.
 endif::[]

docs/modules/ROOT/pages/getting-started/assembly-intro-to-registry-rules.adoc

@@ -5,6 +5,7 @@ include::{mod-loc}shared/all-attributes.adoc[]
 = {registry} content rules
 //If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
 
+[role="_abstract"]
 This chapter introduces the optional rules used to govern registry content and provides details on the available rule configuration:
 
 * xref:registry-rules[]

docs/modules/ROOT/pages/getting-started/assembly-intro-to-the-registry.adoc

@@ -5,6 +5,7 @@ include::{mod-loc}shared/all-attributes.adoc[]
 = Introduction to {registry}
 //If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
 
+[role="_abstract"]
 This chapter introduces {registry} concepts and features and provides details on the supported artifact types that are stored in the registry:
 
 * xref:registry-overview[]

docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-api.adoc

@@ -5,14 +5,22 @@ include::{mod-loc}shared/all-attributes.adoc[]
 = Managing {registry} content using the REST API
 //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 commands to manage schema and API artifacts in {registry}, for example, in a CI/CD pipeline deployed in production. The Registry REST API provides create, read, update, and delete operations for artifacts, versions, metadata, and rules stored in the registry. For detailed information, see the link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation].
+
 This chapter describes the {registry} core REST API and shows how to use it to manage schema and API artifacts stored in the registry:
 
 * xref:registry-rest-api[] 
 * xref:managing-artifacts-using-rest-api[]
+* xref:managing-artifact-versions-using-rest-api[]
+* xref:exporting-importing-using-rest-api[]
 
+[role="_additional-resources"]
 .Additional resources
 * link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation]
 
 //INCLUDES
 include::{mod-loc}getting-started/con-registry-rest-api.adoc[leveloffset=+1]
 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-exporting-importing-using-rest-api.adoc[leveloffset=+1]

docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-maven.adoc

@@ -4,14 +4,19 @@ include::{mod-loc}shared/all-attributes.adoc[]
 [id="managing-registry-artifacts-maven"]
 = Managing {registry} content using the Maven plug-in
 
+[role="_abstract"]
 This chapter explains how to manage schema and API artifacts stored in the registry using the {registry} Maven plug-in:
 
-* xref:managing-artifacts-using-maven-plugin[]
+* xref:adding-artifacts-using-maven-plugin[]
+* xref:downloading-artifacts-using-maven-plugin[]
+* xref:testing-artifacts-using-maven-plugin[]
 
 .Prerequisites
 * See {registry-overview}
 * {registry} must be installed and running in your environment
 * Maven must be installed and configured in your environment
 
 //INCLUDES
-include::{mod-loc}getting-started/proc-managing-artifacts-using-maven-plugin.adoc[leveloffset=+1]
+include::{mod-loc}getting-started/proc-adding-artifacts-using-maven-plugin.adoc[leveloffset=+1]
+include::{mod-loc}getting-started/proc-downloading-artifacts-using-maven-plugin.adoc[leveloffset=+1]
+include::{mod-loc}getting-started/proc-testing-artifacts-using-maven-plugin.adoc[leveloffset=+1]

docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-ui.adoc

@@ -5,6 +5,7 @@ include::{mod-loc}shared/all-attributes.adoc[]
 = Managing {registry} content using the web console
 //If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
 
+[role="_abstract"]
 This chapter explains how to manage schema and API artifacts stored in the registry using the {registry} web console. This includes uploading and browsing registry content, and configuring optional rules:
 
 * xref:configuring-registry-ui[]

docs/modules/ROOT/pages/getting-started/assembly-registry-reference.adoc

@@ -5,6 +5,7 @@ include::{mod-loc}shared/all-attributes.adoc[]
 = {registry} artifact reference
 //If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
 
+[role="_abstract"]
 This chapter provides details on the supported artifact types, states, metadata, and content rules that are stored in {registry}.
 
 * xref:registry-artifact-types[]
@@ -13,7 +14,7 @@ This chapter provides details on the supported artifact types, states, metadata,
 * xref:registry-rule-types[]
 * xref:registry-rule-maturity-matrix[]
 
-
+[role="_additional-resources"]
 .Additional resources
 * For more detailed information, see the link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation]
 

docs/modules/ROOT/pages/getting-started/assembly-using-the-registry-client.adoc

@@ -4,6 +4,7 @@ include::{mod-loc}shared/all-attributes.adoc[]
 [id="using-the-registry-client"]
 = Managing {registry} content using a Java client
 
+[role="_absract"]
 This chapter explains how to use the {registry} Java client:
 
 * xref:registry-client-intro[]

docs/modules/ROOT/partials/getting-started/con-registry-artifacts.adoc

@@ -33,24 +33,24 @@ When a schema or API design is added as an artifact in the registry, client appl
 
 An _artifact group_ is an optional named collection of schema or API artifacts. Each group contains a logically related set of schemas or API designs, typically managed by a single entity, belonging to a particular application or organization. 
 
-You can create artifact groups to organize your schemas and API designs in {registry}. For example, you could create groups to match your `development` and `production` application environment, or your `sales` and `engineering` organization. 
+You can create optional artifact groups when adding your schemas and API designs to organize them in {registry}. For example, you could create groups to match your `development` and `production` application environment, or your `sales` and `engineering` organization. 
 
 Schema and API groups can contain multiple artifact types. For example, you could have Protobuf, Avro, JSON Schema, OpenAPI, and AsyncAPI schema and API artifacts all in the same group.    
 
-You can create schema and API artifacts and groups using the {registry} web console, core REST API, or Maven plug-in.  The following simple example shows using the REST API: 
+You can create schema and API artifacts and optional groups using the {registry} web console, core REST API, or Maven plug-in.  The following simple example shows using the REST API: 
 
 [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-cluster-my-registry-my-project.example.com/apis/registry/v2/groups/my-group/artifacts
+  https://my-registry.example.com/apis/registry/v2/groups/my-group/artifacts
 ----
 
 This example adds an Avro schema with an artifact ID of `share-price` in an artifact group named `my-group`.
 
-NOTE: Schema and API groups are optional when using the {registry} web console. When using the v2 REST API or Maven plug-in, you must specify the `default` group in the API path if you do not create a unique group.   
+NOTE: Specifying a group is optional when using the {registry} web console, and a `default` group is automatically created. When using the v2 REST API or Maven plug-in, you can specify the `default` group in the API path if you do not want to create a unique group.   
 
 [role="_additional-resources"]
 .Additional resources

docs/modules/ROOT/partials/getting-started/con-registry-rest-api.adoc

@@ -10,14 +10,14 @@ 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.
 Artifact metadata::
 Manage details about a schema or API artifact, such as when it was created or modified, and its current state. You can edit the artifact name, description, or label. The artifact group and when the artifact was created or modified are read-only.
-Global rules::
-Configure rules to govern the content evolution of all schema and API artifacts artifacts to prevent invalid or incompatible content from being added to the registry. Global rules are applied only if an artifact does not have its own specific artifact rules configured. 
 Artifact rules::
 Configure rules to govern the content evolution of a specific schema or API artifact to prevent invalid or incompatible content from being added to the registry. Artifact rules override any global rules configured. 
+Global rules::
+Configure rules to govern the content evolution of all schema and API artifacts artifacts to prevent invalid or incompatible content from being added to the registry. Global rules are applied only if an artifact does not have its own specific artifact rules configured. 
 Search::
 Browse or search for schema and API artifacts and versions, for example, by name, group, description, or label.
 Admin::
-Manage logging levels for the {registry} instance at runtime.
+Export or import registry content in a `.zip` file, and manage logging levels for the registry server instance at runtime.
 
 [discrete]
 == Compatibility with other schema registry REST APIs

docs/modules/ROOT/partials/getting-started/con-registry-web-console.adoc

@@ -3,7 +3,7 @@
 [id="registry-web-console"]
 = Manage content using {registry} web console
 
-You can use the {registry} web console to browse and search the schema and API artifacts and groups stored in the registry, and to upload 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 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 use the web console to 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. For more details, see {registry-reference}.
 

docs/modules/ROOT/partials/getting-started/proc-adding-artifacts-using-console.adoc

@@ -16,8 +16,8 @@ You can use the {registry} web console to upload event schema and API design art
 +
 `*\http://MY_REGISTRY_URL/ui*`
 
-. Click *Upload Artifact*, and specify the following:
-** *Group & ID*: Use the default empty settings to automatically generate an ID, or enter an optional artifact group or ID. 
+. Click *Upload artifact*, and specify the following:
+** *Group & ID*: Use the default empty settings to automatically generate an ID and `default` group, or enter an optional artifact group or ID.
 ** *Type*: Use the default *Auto-Detect* setting to automatically detect the artifact type, or select the artifact type from the drop-down, for example, *Avro Schema* or *OpenAPI*.
 +
 NOTE:  The {registry} server cannot automatically detect the *Kafka Connect Schema* artifact type. You must manually select this artifact type.

docs/modules/ROOT/partials/getting-started/proc-adding-artifacts-using-maven-plugin.adoc

@@ -0,0 +1,55 @@
+// Metadata created by nebel
+// ParentAssemblies: assemblies/getting-started/as_installing-the-registry.adoc
+
+[id="adding-artifacts-using-maven-plugin"]
+= Adding schema and API artifacts using the Maven plug-in
+
+[role="_abstract"]
+The most common use case for the Maven plug-in is adding artifacts during a build. You can accomplish this by using the `register` execution goal. 
+
+.Procedure
+* Update your Maven `pom.xml` file to use the `apicurio-registry-maven-plugin` to register an artifact. The following example shows registering Apache Avro and GraphQL schemas:
++
+[source,xml]
+----
+<plugin>     
+  <groupId>io.apicurio</groupId>
+  <artifactId>apicurio-registry-maven-plugin</artifactId>
+  <version>${apicurio.version}</version>
+  <executions>
+      <execution>
+        <phase>generate-sources</phase>
+        <goals>
+            <goal>register</goal>  <1>
+        </goals>
+        <configuration>
+            <registryUrl>http://REGISTRY-URL/apis/registry/v2</registryUrl> <2>
+            <artifacts>
+                <artifact>
+                    <groupId>TestGroup</groupId> <3>
+                    <artifactId>FullNameRecord</artifactId>
+                    <file>${project.basedir}/src/main/resources/schemas/record.avsc</file> 
+                    <ifExists>FAIL</ifExists>
+                </artifact>
+                <artifact>
+                    <groupId>TestGroup</groupId>
+                    <artifactId>ExampleAPI</artifactId> <4>
+                    <type>GRAPHQL</type>
+                    <file>${project.basedir}/src/main/resources/apis/example.graphql</file>
+                    <ifExists>RETURN_OR_UPDATE</ifExists>
+                    <canonicalize>true</canonicalize>
+                </artifact>
+            </artifacts>
+        </configuration>
+    </execution>
+  </executions>
+ </plugin>
+----
+<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.
+<3> Specify the {registry} artifact group ID. You can specify the `default` group if you do not want to use a unique group.
+<4> You can upload multiple artifacts using the specified group ID, artifact ID, and location.
+
+[role="_additional-resources"]
+.Additional resources
+ * For more details on the {registry} Maven plug-in, see the link:https://github.com/Apicurio/apicurio-registry-demo[Registry demonstration example]

docs/modules/ROOT/partials/getting-started/proc-browsing-artifacts-using-console.adoc

@@ -4,7 +4,7 @@
 [id="browsing-artifacts-using-console"]
 = Viewing artifacts using the {registry} web console
 
-You can use the {registry} web console to browse the event schema and API design artifacts stored in the registry. This section shows simple examples of viewing {registry} artifacts, versions, and artifact rules. For more details on the artifact types stored in the registry, see {registry-reference}. 
+You can use the {registry} web console to browse the event schema and API design artifacts stored in the registry. This section shows simple examples of viewing {registry} artifacts, groups, versions, and artifact rules. For more details on the artifact types stored in the registry, see {registry-reference}. 
 
 .Prerequisites
 

docs/modules/ROOT/partials/getting-started/proc-configuring-rules-using-console.adoc

@@ -19,7 +19,7 @@ This section shows a simple example of configuring global and artifact rules. Fo
 +
 `*\http://MY_REGISTRY_URL/ui*`
 
-. For artifact rules, browse the list of artifacts stored in the registry, or enter a search string to find an artifact. You can select to search by a specific artifact *Name*, *Description*, *Label*, or *Everything*.  
+. For artifact rules, browse the list of artifacts stored in the registry, or enter a search string to find an artifact. You can select to search by a specific artifact *Name*, *Group*, *Description*, or *Labels*.  
 
 . Click *View artifact* to view the *Artifact Details*.
 
@@ -28,7 +28,7 @@ This section shows a simple example of configuring global and artifact rules. Fo
 .Configure content rules in {registry} web console
 image::images/getting-started/registry-web-console-rules.png[Configure rules in Registry web console]
 +
-. For global rules, click the *Settings* cog icon at the top right of the toolbar, and click *Enable* to configure a global *Validity Rule* or *Compatibility Rule*, and select the appropriate rule configuration from the drop-down. For more details, see {registry-reference}.
+. For global rules, click *Manage global rules* at the top right of the toolbar, and click *Enable* to configure a global *Validity Rule* or *Compatibility Rule*, and select the appropriate rule configuration from the drop-down. For more details, see {registry-reference}.
 
 . To disable an artifact rule or global rule, click the trash icon next to the rule. 
 

docs/modules/ROOT/partials/getting-started/proc-downloading-artifacts-using-maven-plugin.adoc

@@ -0,0 +1,54 @@
+// Metadata created by nebel
+// ParentAssemblies: assemblies/getting-started/as_installing-the-registry.adoc
+
+[id="downloading-artifacts-using-maven-plugin"]
+= Downloading schema and API artifacts using the Maven plug-in
+
+[role="_abstract"]
+You can use the Maven plug-in to download artifacts from {registry}. This is often useful, for example, when generating code from a registered schema.
+
+.Procedure
+* Update your Maven `pom.xml` file to use the `apicurio-registry-maven-plugin` to download an artifact. The following example shows downloading Apache Avro and GraphQL schemas.
++
+[source,xml]
+----
+<plugin>
+  <groupId>io.apicurio</groupId>
+  <artifactId>apicurio-registry-maven-plugin</artifactId>
+  <version>${apicurio.version}</version>
+  <executions>
+    <execution>
+      <phase>generate-sources</phase>
+      <goals>
+        <goal>download</goal> <1>
+      </goals>
+      <configuration>
+          <registryUrl>http://REGISTRY-URL/apis/registry/v2</registryUrl> <2>
+          <artifacts>
+              <artifact>
+                  <groupId>TestGroup</groupId> <3>
+                  <artifactId>FullNameRecord</artifactId> <4>
+                  <file>${project.build.directory}/classes/record.avsc</file>
+                  <overwrite>true</overwrite>
+              </artifact>
+              <artifact>
+                  <groupId>TestGroup</groupId>
+                  <artifactId>ExampleAPI</artifactId>
+                  <version>1</version>
+                  <file>${project.build.directory}/classes/example.graphql</file>
+                  <overwrite>true</overwrite>
+              </artifact>
+          </artifacts>
+      </configuration>
+    </execution>
+  </executions>
+</plugin>
+----
+<1> Specify `download` as the execution goal.
+<2> Specify the {registry} URL with the `../apis/registry/v2` endpoint.
+<3> Specify the {registry} artifact group ID. You can specify the `default` group if you do not want to use a unique group.
+<4> You can download multiple artifacts to a specified directory using the artifact ID. 
+
+[role="_additional-resources"]
+.Additional resources
+ * For more details on the {registry} Maven plug-in, see the link:https://github.com/Apicurio/apicurio-registry-demo[Registry demonstration example]