Apicurio Studio

Managing Apicurio Registry content using the web console

This chapter explains how to manage schema and API artifacts stored in the registry using the Apicurio Registry web console. This includes uploading and browsing registry content, and configuring optional rules:

Configuring the Apicurio Registry web console

You can configure the Apicurio Registry web console specifically for your deployment environment or to customize its behavior. This section provides details on how to configure optional environment variables for the Apicurio Registry web console.

Prerequisites

  • You must have already installed Apicurio Registry.

Configuring the web console deployment environment

When a user navigates their browser to the Apicurio Registry web console, some initial configuration settings are loaded. Two important configuration properties are:

  • URL for backend Apicurio Registry REST API

  • URL for frontend Apicurio Registry web console

Typically, Apicurio 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.

Procedure

Configure the following environment variables to override the default URLs:

  • REGISTRY_UI_CONFIG_APIURL: Set the URL for the backend Apicurio Registry REST API. For example, https://registry.my-domain.com/apis/registry

  • REGISTRY_UI_CONFIG_UIURL: Set the URL for the frontend Apicurio Registry web console. For example, https://registry.my-domain.com/ui

Configuring the console in read-only mode

You can configure the Apicurio Registry web console in read-only mode as an optional feature. This mode disables all features in the Apicurio Registry web console that allow users to make changes to registered artifacts. For example, this includes the following:

  • Creating an artifact

  • Uploading a new version of an artifact

  • Updating an artifact’s metadata

  • Deleting an artifact

Procedure

Configure the following environment variable to set the Apicurio Registry web console in read-only mode:

  • REGISTRY_UI_FEATURES_READONLY: Set to true to enable read-only mode. Defaults to false.

Adding artifacts using the Apicurio Registry web console

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

Prerequisites

  • Apicurio Registry must be installed and running in your environment

Procedure

  1. Connect to the Apicurio Registry web console on:

    http://MY_REGISTRY_URL/ui

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

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

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

    Artifact Details in Registry web console
    Figure 1. Artifact Details in Apicurio 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.

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

  5. 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.
Additional resources

Viewing artifacts using the Apicurio Registry web console

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

Prerequisites

  • Apicurio Registry must be installed and running in your environment

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

Procedure

  1. Connect to the Apicurio Registry web console on:

    http://MY_REGISTRY_URL/ui

  2. 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 2. Browse artifacts in Apicurio Registry web console

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

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

Configuring content rules using the Apicurio Registry web console

You can use the Apicurio 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

  • Apicurio Registry is installed and running in your environment

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

Procedure

  1. Connect to the Apicurio Registry web console on:

    http://MY_REGISTRY_URL/ui

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

  3. Click View artifact to view the Artifact Details.

  4. 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 Apicurio Registry web console

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

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

Additional resources

Exporting and importing registry content using the Apicurio Registry web console

As an administrator, you can use the Apicurio Registry web console to export data from one Apicurio Registry instance, and import it into another Apicurio 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 .zip format from one Service Registry instance to another instance. All of the artifact data contained in the Apicurio Registry instance is exported in the .zip file.

You can import only Apicurio Registry data that has been exported from another Apicurio Registry instance.
Prerequisites

  • Apicurio Registry instances have been created as follows:

    • The source instance that you are exporting from contains at least one schema or API artifact

    • The target instance that you are importing into is empty to preserve unique IDs

  • You are logged into the Apicurio Registry web console with administrator access:

    http://MY_REGISTRY_URL/ui

Procedure

  1. In the web console for the source Apicurio Registry instance, view the Artifacts page.

  2. Next to the Upload artifact button, click the options icon (three vertical dots), and select Download all artifacts (.zip file) to export the registry data for this instance to a .zip download file.

  3. In the the web console for the target Apicurio Registry instance, view the Artifacts page.

  4. Next to the Upload artifact button, click the options icon, and select Upload multiple artifacts.

  5. Drag and drop or browse to the .zip download file that you exported earlier.

  6. Click Upload and wait for the data to be imported.