Apicurio Studio

Managing Apicurio Registry content using the web console

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 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 core Apicurio Registry server REST API

  • URL for Apicurio Registry web console client

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: Specifies the URL for the core Apicurio Registry server REST API. For example, https://registry.my-domain.com/apis/registry

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

Configuring the web 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:

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

Viewing artifacts using the Apicurio Registry web console

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

Prerequisites

  • Apicurio Registry is installed and running in your environment.

  • You are logged in to the Apicurio Registry web console:

    http://MY_REGISTRY_URL/ui

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

Procedure

  1. On the Artifacts tab, browse the list of artifacts stored in Apicurio 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
    Figure 1. Artifacts in Apicurio Registry web console

  2. Click an artifact to view the following details:

    • Overview: Displays the artifact version metadata such as name, optional group and ID, global ID, content ID, labels, and properties. 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.

  3. If additional versions of this artifact have been added, you can select them from the Version list in page header.

  4. To save the artifact contents to a local file, for example, my-protobuf-schema.proto, click Download at the end of the page.

Additional resources

Adding artifacts using the Apicurio Registry web console

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

Prerequisites

  • Apicurio Registry is installed and running in your environment.

  • You are logged in to the Apicurio Registry web console:

    http://MY_REGISTRY_URL/ui

Procedure

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

      Apicurio Registry cannot automatically detect the Kafka Connect Schema artifact type. You must manually select this artifact type.

    • Artifact: Specify the artifact location 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.

      • From URL: Enter a valid and accessible URL, and click Fetch. For example: https://petstore3.swagger.io/api/v3/openapi.json.

  2. Click Upload and view the artifact details:

    • Overview: Displays the artifact version metadata such as name, artifact ID, global ID, content ID, labels, and properties. 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.

      The following example shows an example Protobuf schema artifact:

      Artifact details in Registry web console
      Figure 2. Artifact details in Apicurio Registry web console

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

    1. Click Add property.

    2. Enter the key name and the value.

    3. Repeat the first two steps to add multiple properties.

    4. Click Save.

  4. To save the artifact contents to a local file, for example, my-protobuf-schema.proto, click Download at the end of the page.

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

  6. To delete an artifact, click Delete in the page header.

    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

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

  • You are logged in to the Apicurio Registry web console:

    http://MY_REGISTRY_URL/ui

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

Procedure

  1. On the Artifacts tab, browse the list of artifacts in Apicurio 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.

  2. Click an artifact to view its version details and content rules.

  3. In Content rules, click Enable to configure an validity rule or compatibility rule for artifact content, and select the appropriate rule configuration from the list, for example, Full for the validity rule.

    Configure rules in Registry web console
    Figure 3. Artifact content rules in Apicurio Registry web console

  4. To access global rules, click the Apicurio Registry instance, and click the Global rules tab. Click Enable to configure a global validity rule or compatibility rule for all artifact content, and select the appropriate rule configuration from the list.

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

Additional resources

Configuring Apicurio Registry instance settings using the web console

As an administrator, you can use the Apicurio Registry web console to configure dynamic settings for Apicurio Registry instances at runtime. You can manage configuration options for features such as authentication, authorization, and API compatibility.

Authentication and authorization settings are only displayed in the web console if authentication was already enabled when the Apicurio Registry instance was deployed. For more details, see Configuring your Apicurio Registry deployment.
Prerequisites

  • The Apicurio Registry instance is already deployed.

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

    http://MY_REGISTRY_URL/ui

Procedure

  1. In the Apicurio Registry web console, click the Settings tab.

  2. Select the settings that you want to configure for this Apicurio Registry instance:

    Table 1. Authentication settings
    Setting Description

    HTTP basic authentication

    Displayed only when authentication is already enabled. When selected, Apicurio Registry users can authenticate using HTTP basic authentication, in addition to OAuth. Not selected by default.
    Table 2. Authorization settings
    Setting Description

    Anonymous read access

    Displayed only when authentication is already selected. When selected, Apicurio 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.

    Artifact owner-only authorization

    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.

    Authenticated read access

    Displayed only when authentication is already enabled. When selected, Apicurio Registry grants at least read-only access to requests from any authenticated user regardless of their user role. Not selected by default.
    Table 3. Compatibility settings
    Setting Description

    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 Apicurio Registry instances based on the v1 Core Registry API. Not selected by default.
    Table 4. Web console settings
    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 Apicurio 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.
Additional resources

Changing an artifact owner using the Apicurio Registry web console

As an administrator or as an owner of a schema or API artifact, you can use the Apicurio Registry web console to change the artifact owner to another user account.

This feature is useful if Artifact owner-only authorization is set for the Apicurio Registry instance on the Settings tab so that only owners or administrators can modify artifacts. For example, you might need to change owner if the owner user leaves the organization or the owner account is deleted.

The Artifact owner-only authorization setting and the artifact Owner field are displayed only if authentication was enabled when the Apicurio Registry instance was deployed. For more details, see Configuring your Apicurio Registry deployment.
Prerequisites

  • The Apicurio Registry instance is deployed and the artifact is created.

  • You are logged in to the Apicurio Registry web console as the artifact’s current owner or as an administrator:

    http://MY_REGISTRY_URL/ui

Procedure

  1. On the Artifacts tab, browse the list of artifacts stored in Apicurio 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.

  2. Click the artifact that you want to reassign.

  3. In the Version metadata section, click the pencil icon next to the Owner field.

  4. In the New owner field, select or enter an account name.

  5. Click Change owner.

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 a .zip file from one Apicurio 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 tab.

  2. Click the options icon (three vertical dots) next to Upload artifact, 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 tab.

  4. Click the options icon next to Upload artifact, 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.