17.4.7 Managing REST Source Catalogs

Create a catalog of REST Data Source metadata that can be used by all applications in a workspace to create REST Data Sources.

REST Source Catalogs contain metadata about REST Data Sources. Developers can search and browse a catalog and then create REST Data Sources for their applications. You can share REST Source Catalogs by exporting the REST Data Source catalog to a file and then importing it into another workspace or another instance.

17.4.7.1 Creating a REST Source Catalog

Create a REST Source Catalog in Workspace Utilities.

To create a REST Source Catalog:

  1. Navigate to the REST Source Catalogs page:
    1. On the Workspace home page, click the App Builder icon.
    2. On the App Builder, click the Workspace Utilities icon.
    3. On the Workspace Utilities page, click REST Source Catalogs.
      The REST Source Catalogs page appears. REST Source Catalogs are organized into categories called groups. First create a group and then create the catalog.
  2. Create a group:
    1. From the Tasks list, Manage Catalog Groups.
    2. Click Create Group.
    3. In the Catalog Group Details dialog:
      • Name - Specify the name of the catalog group.

      • Description - Describe the purpose of the group.

      • Click Create.

  3. Click the REST Source Catalogs breadcrumb to return to the REST Source Catalogs page.
  4. Create a catalog:
    1. Click Create Catalog.
    2. In the REST Source Catalog Details dialog:
      • Group - Select a group used to organize the catalog and assist developers when creating services.

      • Name - Specify the name of the catalog. Catalog names must be unique within a workspace.

      • Internal Name - Specify an internal name of the catalog. The Internal Name is used to identify a catalog across multiple APEX instances. If a catalog is imported and a catalog with the same internal name already exists, then the existing catalog will be overwritten.

      • Description - Describe the REST Source Catalog.

      • Click Create.

  5. Create the REST Data Sources to be included in the catalog. See Creating a REST Data Source.
  6. Asssign the REST Data Source with the REST Source Catalog:
    1. Edit the REST Data Source. Click the REST Source Name.
    2. Under REST Source Catalog, click Save to Catalog.
    3. In the Save to REST Source Catalog dialog, verify the following:
      • Catalog Group - Select a Catalog Group. If the service will not be added to an existing catalog, select Add a new Catalog Group and follow in on-screen instructions.

      • Catalog - Select the Catalog to which the service will be added. Choose Add a new Catalog if the service will not be added to an existing catalog.

      • REST Source Name - Displays the current REST Source Name.

    4. Click Save to Catalog.
  7. Repeat the previous step for each REST Data Source to be added to the catalog.

17.4.7.2 Creating a REST Source Catalog from OpenAPI

Create a REST Source Catalog from an OpenAPI file.

A single OpenAPI file can contain a full catalog of REST APIs. Upload an Open API fil and Oracle APEX generates a REST Catalog from it with a REST Source template for each of the contained API descriptions. You can then create REST Sources from a catalog.

To create a REST Source Catalog from an OpenAPI file:

  1. Navigate to the REST Source Catalogs page:
    1. On the Workspace home page, click the App Builder icon.
    2. On the App Builder, click the Workspace Utilities icon.
    3. On the Workspace Utilities page, click REST Source Catalogs.
      The REST Source Catalogs page appears. REST Source Catalogs are organized into categories called groups. First create a group and then create the catalog.
  2. If needed, create a group:
    1. From the Tasks list, Manage Catalog Groups.
    2. Click Create Group.
    3. In the Catalog Group Details dialog:
      • Name - Specify the name of the catalog group.

      • Description - Describe the purpose of the group.

      • Click Create.

  3. Click the REST Source Catalogs breadcrumb to return to the REST Source Catalogs page.
  4. Click Create from OpenAPI.
  5. On Upload OpenAPI:
    1. Upload File - Upload the OpenAPI document. Options include:
      • Drag and Drop - Drag and drop the file to the Upload File region in the center of the page.
      • Choose File - Click Choose File and then navigate to and select the file.
    2. OpenAPI Endpoint URL - As an alternative to uploading the JSON file, enter the URL where the OpenAPI information is available.
    3. Click Next.
  6. The Catalog from OpenAPI dialog appears with the following fields:
    1. Group - Select the group used to organize the catalog and assist developers when creating services.
    2. Catalog - Select an existing catalog to update all services within that catalog or select Create New Catalog.
    3. Name - The name of the catalog. Catalog names must be unique within a workspace.
    4. Internal Name - An internal name of the catalog. The Internal Name is used to identify a catalog across multiple APEX instances. If a catalog is imported and a catalog with the same internal name already exists, then the existing catalog will be overwritten.
    5. Description - Describes the REST Source Catalog.
    6. Default REST Source Type - Specifies the REST Data Source type.
    7. Default Authentication - Select a default authentication type. An empty credential of this type will be created when a REST Data Source is created from the catalog. The credential name and secret will need to be provided at that time. Options include:
      • No Authentication
      • Basic Authentication
      • OAuth2 Client Credentials Flow
      • Oracle Cloud Infrastructure (OCI)
      • Certificate/Private Key Pair
      • HTTP Header
      • URL Query String
    8. Default Token Server URL - Only displays if Default Authentication is set to OAuth2 Client Credentials Flow.

      Enter the URL of a token server. This token server is to be used for REST APIs within the OpenAPI file, which are protected by an OAuth2 Client Credentials authentication flow.

    9. Catalog Refresh URL - Provide a URL where the catalog export file can be downloaded from, in order to refresh the REST Source Catalog.
    10. If Catalog Refresh URL has a value, two more attributes appear:
      • Proxy Server - Proxy server to use when refreshing the REST Source Catalog. If not set, the Oracle APEX instance proxy will be used (if defined).
      • Web Credential - Identifies the Web Credentials to use when refreshing a catalog. Use this Web Credential if the refresh endpoint URL requires authentication.
    11. Click Next.
  7. On REST Source Type Default Parameters - The parameters that appear depend upon the Default REST Source Type specified on the previous page.
    1. Edit the fields. To learn more about a parameter, see field-level Help.
    2. Click Create.
    The catalog appears.

17.4.7.3 Editing a REST Source Catalog

Edit an existing REST Source Catalog on the REST Source Catalogs page.

To edit a REST Source Catalog:

  1. Navigate to the REST Source Catalogs page:
    1. On the Workspace home page, click the App Builder icon.
      The App Builder home page appears.
    2. Click the Workspace Utilities icon.
    3. On the Workspace Utilities page, click REST Source Catalogs.
      The REST Source Catalogs page appears. REST Source Catalogs are organized into categories called groups.
  2. To edit a catalog details:
    1. Click the Catalog name.
      The REST Source Catalog Details dialog appears.
    2. Edit the appropriate attributes:
      • Group - Select a group to organize the catalog and assist developers when creating services.
      • Name - Edit the catalog name. Catalog names must be unique to a workspace.
      • Internal Name - Identifies a catalog across multiple APEX instances. If a catalog is imported, and a catalog with the same internal name already exists, then the existing catalog will be overwritten.
      • Description - Described the REST Source Catalog
      • Refresh Endpoint URL - Provide a URL where the catalog export file can be downloaded from, in order to refresh the REST Source Catalog.
    3. Click Apply Changes.
  3. To delete a catalog.
    1. Click the Catalog name.
    2. On the REST Source Catalog Details dialog, click Delete.
  4. To view catalog services:
    1. In the Contents column, click the Services button.
      The Catalog Services page appears.
    2. To a specific service, click the service name.

      The service details appear.

      Although you may edit the descriptive data such as the catalog service Name or Description, edit other details such as data profiles, operations, parameters through the original REST Data Source definition.

  5. To associate a new REST Data Source with a catalog:
    1. Navigate to REST Data Source.
    2. Under REST Source Catalog, click Save to Catalog.
    3. In the Save to REST Source Catalog dialog, verify the options and click Save to Catalog.

17.4.7.4 Managing Catalog Groups

Use Catalog Groups to organize catalogs into categories..

To manage Catalog Groups:

  1. Navigate to the REST Source Catalogs page:
    1. On the Workspace home page, click the App Builder icon.
      The App Builder home page appears.
    2. Click the Workspace Utilities icon.
    3. On the Workspace Utilities page, click REST Source Catalogs.
      The REST Source Catalogs page appears.
  2. From the Tasks menu on the right side of the page, click Manage Catalog Groups.
  3. To add a Catalog Group:
    1. Click Create Group.
    2. In the Catalog Group Details dialog:
      • Name - Specify the name of the catalog group.

      • Description - Describe the purpose of the group.

      • Click Create.

  4. To edit a catalog group.
    1. Click the Catalog Name.
    2. In the Catalog Group Details dialog:
      • Name - Specify the name of the catalog group.

      • Description - Describe the purpose of the group.

      • Click Apply Changes.

  5. To delete a Catalog Group:
    1. Click the Catalog Name.
    2. Click Delete.

17.4.7.5 About Exporting and Importing a REST Source Catalog

Move REST Source Catalog to another instance by exporting it to a file and then importing the file into the target instance.

Exporting a REST Source Catalog to another instance involves the following steps:

  1. Create the REST Source Catalog.
  2. Export the REST Source Catalog. See Exporting a REST Source Catalog.
  3. Import the exported file into the target Oracle APEX instance. See Importing a REST Source Catalog.
  4. Install the exported file either directly after importing the file, or later from the Export Repository. See Installing Other Files from the Export Repository.