Managing schemas and APIs using the Service Registry web console

Guide
  • Red Hat OpenShift Service Registry 1
  • Updated 07 December 2021
  • Published 24 September 2021

Managing schemas and APIs using the Service Registry web console

Guide
Red Hat OpenShift Service Registry 1
  • Updated 07 December 2021
  • Published 24 September 2021

Manage schema and API artifacts stored in the Red Hat OpenShift Service Registry cloud service using the Service Registry web console.

You can use the web console to browse and search the schema and API artifacts and optional groups stored in Service Registry, and to add new schema and API artifacts, groups, and versions. You can search for artifacts by label, name, group, or description. You can view an artifact’s content or its available versions, or download an artifact file locally.

You can 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.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code and documentation. We are beginning with these four terms: master, slave, blacklist, and whitelist. Due to the enormity of this endeavor, these changes will be gradually implemented over upcoming releases. For more details on making our language more inclusive, see our CTO Chris Wright’s message.

Viewing artifacts using the Service Registry web console

You can use the Service Registry web console to browse the event schema and API design artifacts stored in the registry. This section shows simple examples of viewing Service Registry artifacts, groups, versions, and artifact rules.

Prerequisites
  • You must have access to the Service Registry web console

  • Artifacts must have been added to the registry using the Service Registry web console, REST API, command line, Maven plug-in, or a Java client application.

Procedure
  1. Connect to the Service Registry web console on:

    https://console.redhat.com/application-services/service-registry/

  2. Click your existing Service Registry instance.

  3. 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 Name, Group, Description, or Labels.

    Browse artifacts in Registry web console
    Figure 1. Browse artifacts in Service Registry web console
  4. Click an artifact to view the Artifact Details:

    • Info: Displays the artifact name and optional group, description, lifecycle status, when created, and last modified. Also displays artifact Content Rules that you can enable and configure.

    • Documentation (OpenAPI only): Displays automatically-generated REST API documentation.

    • Content: Displays a read-only view of the full artifact content.

  5. Select to view a different artifact Version from the drop-down, if additional versions have been added.

Adding artifacts using the Service Registry web console

You can use the Service Registry web console to upload event schema and API design artifacts to the registry. This section shows simple examples of uploading Service Registry artifacts and adding new artifact versions.

Prerequisites
  • You must have access to the Service Registry web console

Procedure
  1. Connect to the Service Registry web console on:

    https://console.redhat.com/application-services/service-registry/

  2. Click your existing Service Registry instance, or click Create Service Registry instance to provision a new one.

  3. 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.

      Service Registry cannot automatically detect the Kafka Connect Schema artifact type. You must manually select this artifact type.
    • Artifact: Drag and drop or click Browse to upload a file, for example, my-schema.json or my-openapi.json.

  4. Click Upload and view the Artifact Details. This example shows an Avro schema artifact:

    Artifact Details in Registry web console
    Figure 2. Artifact Details in Service Registry web console
    • Info: Displays the artifact name and optional group, description, lifecycle status, when created, and last modified.

      Click the Edit Artifact Metadata pencil icon to edit the artifact name and description or add labels, and click Download to download the artifact file locally. Also displays artifact Content Rules that you can enable and configure.

    • Documentation (OpenAPI artifacts only): Displays automatically-generated REST API documentation.

    • Content: Displays a read-only view of the full artifact content.

  5. Click Upload new version to add a new artifact version, and drag and drop or click Browse to upload the file, for example, my-schema.json or my-openapi.json.

  6. To delete an artifact, click the delete button next to Upload new version.

    Deleting an artifact deletes the artifact and all of its versions, and cannot be undone. Artifact versions are immutable and cannot be deleted individually.

Configuring content rules using the Service Registry web console

You can use the Service Registry web console to configure optional rules to prevent invalid content from being added to the registry. All configured artifact rules or global rules must pass before a new artifact version can be uploaded to the registry. Configured artifact rules override any configured global rules. This section shows a simple example of configuring global and artifact rules.

Prerequisites
  • You have access to the Service Registry web console

  • Artifacts have been added to the registry using the Service Registry web console, REST API, command line, Maven plug-in, or a Java client application.

Procedure
  1. Connect to the Service Registry web console on:

    https://console.redhat.com/application-services/service-registry/

  2. Click your existing Service Registry instance.

  3. 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.

  4. Click View artifact to view the Artifact Details.

  5. In Content Rules, click Enable to configure an artifact Validity Rule or Compatibility Rule, and select the appropriate rule configuration from the drop-down.

    Configure rules in Registry web console
    Figure 3. Configure content rules in Service Registry web console
  6. For global rules, click the Global Rules tab at the top left of your Service Registry instance, and click Enable to configure a global Validity Rule or Compatibility Rule, and select the appropriate rule configuration from the drop-down.

  7. To disable an artifact rule or global rule, click the trash icon next to the rule.