6 Editing Metadata of API Assets in Oracle API Catalog

This chapter describes editing the metadata of harvested API assets in Oracle API Catalog and publishing API assets so users with the developer role can discover and use them.

After an API asset is harvested, as described in Chapter 5, "Configuring and Using Automated Harvesting", an Oracle API Catalog user with the curator or admin role can edit its metadata to facilitate a developer's discovery and understanding of an API. For instance, a curator can add keywords that make the asset more visible when searching for specific key words. The curator can also add a detailed description and a link to documentation for each API harvested and added to Oracle API Catalog.

For more information about the roles discussed in this section, see the "Role-Based Features" section in the Oracle Fusion Middleware Concepts Guide for Oracle API Catalog.

This chapter contains the following sections:

6.1 Editing the Metadata of an API Asset

A user with the curator role should add metadata to API assets after they are harvested.

To edit the metadata of an API asset:

  1. Search for an API asset for which you want to edit the metadata. See the "Finding Assets" section in the Oracle Fusion Middleware Developer's Guide for API Catalog for more information about searching for APIs.

  2. Click an API on the Search Results page to open its detail page.

  3. Click the Edit icon, as shown in Figure 6-1. The API's Edit Asset page is displayed.

    Figure 6-1 Edit Icon, API Detail Page

    Description of Figure 6-1 follows
    Description of ''Figure 6-1 Edit Icon, API Detail Page''

    Note:

    Not all of the information on an API's asset detail page can be edited. For example, an API"s Technical Information, WSDL Summary, and Harvester Properties cannot be edited.

  4. Add any new metadata (or edit existing metadata) associated with the API.

    The metadata you can edit are described as follows:

    • Name: The name of the API asset as it appears in Oracle API Catalog. The harvester automatically populates this field. You do not have to keep the default name; you can change this to anything that makes sense for this particular API. This field is required.

    • Version: The version of the API asset. The harvester supplies a default version based on information that it finds in the composite; if no version information is found in the composite, the harvester assigns it a default version. You can change this to anything that makes sense for this particular API.

    • Keywords: Keywords that users can use to find this asset in search results. You can also include name value pairs, such as platform=linux. Separate each keyword with a comma.

      Note:

      The maximum number of characters that can be entered into the Keyword field is 4000.

    • API Status: The published status of the API. When an API is initially harvested, this is set to Draft by default. When you want to publish this asset to make it discoverable by developers, select Published from this list. See Section 6.2, "Publishing an API Asset" for more information about publishing an API asset.

    • Active Status: The Active Status of an API. Active is selected by default. Select Retired when an API is retired.

      Note:

      When an API is retired, it will not be discoverable by developers, regardless of the published status.

    • Description: The detailed description of the API's functionality, including functionality and other relevant information about using the API, such as a secure endpoint URL.

      You can use HTML tags to add links or new elements, such as a contacts element, in the description field. For example, adding <b>Contacts:</b>John Smith<br> to the description field adds a searchable Contacts element containing the name John Smith.

      The cmee.asseteditor.enable-embedded-html-asset-description system setting must be enabled for HTML tags to function in this field.

      Note:

      The maximum number of characters that can be entered into the Description field is 4000.

    • Documentation URL: The URL to documentation for this API. You can link to a single document, a wiki page, or another page that collects multiple doc links. This URL will become a clickable link on the API's asset detail page.

    • Icon: Select one of the following:

      • Icon URL: The URL pointing to the icon that you want to use for this API. Click Preview to display a preview of the icon.

      • Upload Icon: Click Browse to browse for an icon on your local machine to use for this API.

  5. Click Save to save your changes.

6.2 Publishing an API Asset

After being harvested, an API asset is not discoverable by developers. A user with the curator or admin role must publish the API to make it visible to developers.

To publish an API:

  1. Search for an API asset that you want to publish. See the "Finding Assets" section in the Oracle Fusion Middleware Developer's Guide for API Catalog for more information about searching for APIs.

    Tip:

    Select Draft from the list to return only APIs that have not yet been published.

  2. Click an API on the Search Results page to open its detail page.

  3. Click the Edit icon. The API's Edit Asset page is displayed.

  4. From the API Status list, select Published.

  5. Click Save to save your changes. Users with the developer role can now discover this asset by search. This API will also be displayed in the Recently Published APIs section of the Oracle API Catalog home page.

6.3 Using EasyLinks

EasyLinks may be useful if you want to add a link to an API detail page in documentation or on another API detail page.

The EasyLink icon is displayed on API pages, as shown in Figure 6-2. These icons open a pop-up window that displays a URL to the API detail page that can copied to the clipboard and pasted into documents or email messages as pointers to specific APIs.

To add a link to an API detail page:

  1. Navigate to the detail page of the API that you want to create a link to.

  2. Click the EasyLink icon.

  3. Paste the URL from the pop-up window to where you want to create the link.

  4. If adding the link to the Description field of an API's detail page, edit the link so that it opens in a new tab by adding a target="_blank" attribute to the link.

6.4 Deleting an Asset

To delete an asset in Oracle API Catalog, perform the following steps:

Note:

Only users with the admin role can delete assets from Oracle API Catalog.

  1. Perform a search for the API asset(s) that you want to remove from Oracle API Catalog.

  2. To delete an API:

    • To delete an API from the Search Results screen, select the check box next to each API that you want to delete, and then click Delete. You can delete multiple APIs simultaneously using this method.

    • To delete an API from its detail page, open the detail page for the API you want to delete, and then click Delete.