2 Getting Started with the Oracle API Catalog Console

This chapter describes how to use the Oracle API Catalog console.

This chapter includes the following sections:

2.1 Getting Started

This section describes the following processes:

2.1.1 Logging in to Oracle API Catalog

To log in to Oracle API Catalog, perform the following steps:

  1. Using a browser, open Oracle API Catalog.

  2. On the login screen, enter the appropriate information in the Username and Password boxes.

  3. Click Sign In.

2.1.2 The Default View

After you have logged in, you will see the Oracle API Catalog home page, as shown in Figure 2-1. Note that the APIs in the image are for illustrative purposes only; OAC does not include example APIs.

Figure 2-1 Oracle API Catalog Home Page

Description of Figure 2-1 follows
Description of "Figure 2-1 Oracle API Catalog Home Page"

The Oracle API Catalog Menu Bar

The Oracle API Catalog menu bar runs across the top of the console, and enables you to navigate to the various tools and features within Oracle API Catalog.

The elements that appear in the menu bar are determined by the role of the user who is currently signed in. For example, the list with published status options in the search region and the Admin button do not appear when a user with the developer role is signed in. See Section 2.2, "User Role Descriptions" for more information about user roles in Oracle API Catalog.

  • Search

    The search region is the primary method of discovering APIs in API Catalog.

    Use the search region to find assets using criteria of your choice. See Section 2.3.1.1, "Performing Standard Searches" for more information about searches.

  • API Catalog Home

    Click the API Catalog Home button to navigate to the API Catalog home page. The API Catalog home page displays the API Search, in addition to recently published and recently reviewed APIs.

  • My APIs

    Click the My APIs button to navigate to the My APIs page. The My APIs page collects all of the APIs that you have declared interest in, providing quick access to the detail and review submission pages for these APIs.

    See Section 2.3.3, "Managing My APIs" for more information about the My APIs page.

  • Admin

    Click the Admin button to navigate to the Admin page. From the Admin page, users with the appropriate roles can configure the infrastructure of API Catalog. For more information on these tasks, see the Oracle Fusion Middleware Administrator's Guide for Oracle API Catalog.

    Note:

    The Admin page is available only to users with the admin role.
  • User Menu

    Click your name to expand the User Menu. From this menu. you can access Help, change your password, or sign out of Oracle API Catalog.

2.1.3 Logging Out of Oracle API Catalog

To log out of Oracle API Catalog:

  1. From the Oracle API Catalog menu bar, click the menu icon to the right of the user name to expand the user menu.

  2. Select Sign Out.

2.2 User Role Descriptions

Oracle API Catalog users are defined by roles. Each role has certain permissions that enable users to fulfill specific tasks.

The default roles shipped with Oracle API Catalog are described below.

  • developer: Users with the developer role have the ability to search OAC for registered APIs from the OAC console or using the Oracle Enterprise Repository JDeveloper plug-in. The developer can examine the API metadata to better understand the API. The developer also has the ability to declare interest in the API and submit ratings and reviews for an API.

    This guide describes the tasks performed by users with the developer role.

  • curator: In addition to the capabilities available to the developer role, users with the curator role can run the harvester to create new API assets in OAC. After API assets have been created, curators edit them to update their metadata. The curator also has the ability to publish an API, which makes the API available for discovery by developers.

    For more information about the lifecycle tasks available to users with the curator role, see the "Introducing Asset Lifecycle Administration Tasks" section in the Oracle Fusion Middleware Administrator's Guide for Oracle API Catalog.

  • admin: In addition to the capabilities available to the curator and the developer roles, users with the admin role have access to the Admin page in OAC. From this page users with this role can administer the infrastructure of OAC by editing system settings, creating new users, creating new departments, managing sessions, and using the import/export tool. Users with this role can also configure the security features included with OAC.

    For more information about infrastructure administration tasks available to users with the admin role, see the "Introducing Infrastructure Administration Tasks" section in the Oracle Fusion Middleware Administrator's Guide for Oracle API Catalog.

    For more information about the security configuration tasks available to users with the admin role, see the "Introducing Security Administration Tasks" section in the Oracle Fusion Middleware Administrator's Guide for Oracle API Catalog.

2.3 Exploring the Asset Lifecycle

This section describes how you can work with assets in Oracle API Catalog. This section includes the following topics:

Note:

The only asset type available for Oracle API Catalog is the API Asset type.

2.3.1 Finding Assets

You can find assets in Oracle API Catalog using various methods. This section includes some of the methods to find assets in Oracle API Catalog:

Note:

The only asset type available for Oracle API Catalog is the API Asset type.

2.3.1.1 Performing Standard Searches

Perform searches from the Search region in the Oracle API Catalog menu bar.

  1. Enter a keyword into the Search field.

  2. (Optional) Select a service type (All Services, REST, or SOAP) from the list.

  3. (Optional) Select a published status (Published, Draft, or All APIs) from the list.

    Note:

    You must have the curator or admin roles to view the list with published status options in the search region.
  4. Click the Search button. The Search Results page displays the results.

2.3.1.1.1 Searching For a Specific Field

You can search specific fields, such as Name and Description.

Note:

The cmee.search.specific.field system setting must be enabled to search specific fields. See "System Settings Overview" in the Oracle Fusion Middleware Administrator's Guide for Oracle API Catalog for more information about system settings.
  • Use the following syntax to perform a search on myAsset in the name field only:

    name:myAsset

  • Use the following syntax to perform a search on myAsset in the description field only:

    description:myAsset or desc:myAsset

Search results appear in the Search Results tab, as displayed in Figure 2-2.

Figure 2-2 Oracle API Catalog Search Results Tab

Description of Figure 2-2 follows
Description of "Figure 2-2 Oracle API Catalog Search Results Tab"

From the Search Results tab, you can export the details of the results to a zip, PDF, or Microsoft Excel file. See Section 2.3.6, "Exporting Asset Details" for more information.

Users with the admin role can also delete assets from OAC from the search results page. See the "Editing Metadata of API Assets in Oracle API Catalog" chapter in the Oracle Fusion Middleware Administrator's Guide for Oracle API Catalog for more information.

2.3.1.2 Finding APIs on the API Catalog Home Page

The API Catalog home page features assets that have recently been published or reviewed. This allows you to quickly access the most recently changed APIs that you may be interested in.

To find recently published APIs:

  1. Click the API Catalog Home button to navigate to the API Catalog home page.

  2. Review the APIs displayed in the Recently Published APIs section. The APIs that a curator have most recently published are displayed here.

To find recently reviewed APIs:

  1. Click the API Catalog Home button to navigate to the API Catalog home page.

  2. Review the APIs displayed in the Latest Reviews section. The APIs that have been reviewed most recently are displayed here.

2.3.2 Evaluating Assets

The API Detail can be viewed in tabular or frame format. The API Detail page provides a wide variety of information on the use, functionality, and history of an API. Typically, asset metadata is provided and reviewed by the curator before presentation through Oracle Enterprise Repository.

After performing a search, click any asset listed in the search results to open its API Detail in a new tab.

Search results on the Asset Search in the Web Console are now limited by default, to improve initial search performance. The number of results is configurable on the Admin | System Properties screen: "cmee.search.assets.maxresults". If a search exceeds the maximum number of results, the search results screen shows a result count like "Results (1000 of 2345)", and a link "Show All" that brings back all of the results.

Note:

The only asset type available for Oracle API Catalog is the API Asset type.

2.3.3 Managing My APIs

My APIs collects the APIs that you are interested in. Every API that you've added to your My APIs list is displayed on your My APIs page. Each user has their own My APIs page, so APIs that another user has expressed interest in but you have not expressed interest in will not be displayed. Once an API has been added to My APIs, you can add reviews and ratings viewable by other users.

This section describes the following tasks:

2.3.3.1 Adding an API to My APIs

You should add an API to your My APIs list if you are using it or are interested in using it.

Note:

You should always add APIs that you use to My APIs. This is how usage metrics are determined in Oracle API Catalog.

To add an API to My APIs:

  1. Find an API that you are interested in by performing a search, as described in Section 2.3.1.1, "Performing Standard Searches".

  2. Click on an API on the Search Results page to open that API's detail page.

  3. After reviewing the API's metadata, click the Add to My APIs icon, as shown in Section 2.3.3.1, "Add to My APIs Icon". This API now appears on the My APIs page.

    Figure 2-3 Add to My APIs Icon

    Description of Figure 2-3 follows
    Description of "Figure 2-3 Add to My APIs Icon"

    Note:

    If the API has already been added to My APIs, the Submit a Review icon replaces the Add to My APIs icon.

2.3.3.2 Removing an API from My APIs

To remove an API from the My APIs:

  1. Click the My APIs button to display all of the APIs that have been added.

  2. Click the Remove icon for each API that you want to remove, as shown in Figure 2-4.

    Figure 2-4 Remove API Icon

    Description of Figure 2-4 follows
    Description of "Figure 2-4 Remove API Icon"

2.3.3.3 Viewing an API's Usage History

Viewing an API's history gives you insight into how the API is being used. Oracle API Catalog tracks how many users have added an API to their My APIs page.

Note:

An API must first be added to a user's My APIs before that user can track its usage. See Section 2.3.3.1, "Adding an API to My APIs" for more information.

To view the history of an API:

  1. Click on the My APIs button to open My APIs.

  2. Find the API you want to review on the My APIs page. Click on its title to open the API's detail page.

  3. On the API's detail page, click View Usage History, as shown in Figure 2-5.

    Figure 2-5 Usage Region on an API Detail Page

    Description of Figure 2-5 follows
    Description of "Figure 2-5 Usage Region on an API Detail Page"

    The Usage dialog opens. The Used graphs display how many users have added this API to their My API page over the given time spans. The table at the bottom of the dialog display the users that currently have this API added to My APIs.

2.3.4 Consuming URLs from an API's Detail Page

An API's detail page includes information to help you incorporate the API into your application. Using the OAC console, you can find an endpoint URL that you can use to interact with the API. You can also find the URL of a WSDL or WADL file that you can import into your IDE.

2.3.4.1 Using the Endpoint URL of an API

To find the endpoint for an API that can be consumed into your IDE:

  1. Find the API for which you want to view the endpoint URL in your My APIs list. Open its detail page.

  2. The Endpoint URL is displayed in the Technical Information region.

  3. You can interact with the API through this URL by copying and pasting it into your code or your IDE.

2.3.4.2 Using the WSDL or WADL of an API

To view the WSDL or WADL file associated with the API:

  1. Find the API for which you want to view the WSDL or WADL file in your My APIs list. Open its detail page.

  2. The region in which the URL is displayed differs depending on if you are viewing a SOAP service or REST service:

    • For a SOAP service, the File Location URL is displayed in the WSDL Summary region.

    • For a REST service, the WADL URL is displayed in the Technical Information region.

  3. Click the URL to view the file's contents. You can also right-click the URL, save the file, and import it into your application in your IDE.

2.3.5 Reviewing Assets

Individuals who have used an asset can provide a written review and a rating for the asset. These reviews are useful to other users, as well as to those who manage the assets. It provides an opportunity for users to share their experiences with others in the community.

Note:

The only asset type available for Oracle API Catalog is the API Asset type.

Follow these steps to rate an asset and to submit a review.

Note:

You can only review assets that have been added to My APIs.
  1. Find the API you want to review on the My APIs page. Click on its title to open the API's detail page.

  2. Click Submit a Review icon, as shown in Figure 2-6. The Submit a Review dialog is displayed, as shown in Figure 2-7.

    Figure 2-6 Submit a Review Icon

    Description of Figure 2-6 follows
    Description of "Figure 2-6 Submit a Review Icon"

    Figure 2-7 Submit a Review

    Description of Figure 2-7 follows
    Description of "Figure 2-7 Submit a Review"

  3. Select the appropriate rating from the Rating list.

  4. Enter the appropriate review information in the Comments text box.

  5. Click Submit. A confirmation message appears.

  6. Close the window, or click click here to display the review.

2.3.6 Exporting Asset Details

The details of an API can be exported in any one of the following forms:

2.3.6.1 Exporting Detail to Excel

You can export API information to an Excel spreadsheet. This may be helpful if you want to import an API's information into another tool.

You can export details to an Excel file using the following methods:

Note:

The export will fail if a field containing a hyperlink (for instance, the Endpoint URI or WADL URL fields) contains more than 128 characters.
2.3.6.1.1 Export an Excel File from Search Results

This procedure is performed on the Oracle API Catalog home page.

  1. Perform a search by entering keywords in the Search field. Select a service type and published status from the lists, as necessary, to refine the search.

  2. Select one or more APIs from the search results by placing a check in the check box that appears to the left of APIs listed in the Search Results page.

  3. Select Export to Excel in the list at the top of the pane.

    Note:

    The Export to Excel option is displayed, only when the cmee.asset.registry.export.excel property is enabled. This is enabled by default, but if you are migrating, then you might face an issue if this property is not enabled.
  4. Click Go. Export progress is indicated in the progress window, with the following options:

    • Click Terminate Job to end the export.

    • Click View Audit Log to open a log of the export process.

  5. When the export is complete, click View Excel Spreadsheet in the progress window. The spreadsheet opens in Microsoft Excel.

    APIs are listed horizontally; API Detail elements are indicated by the light-green background.

2.3.6.1.2 Export an Excel file from the Detail Page

This procedure is performed on the Oracle API Catalog home page.

  1. Locate the appropriate API.

  2. Click the Excel icon in the detail page. Export progress is indicated in the progress window.

  3. When the export is complete, click View Excel Spreadsheet in the progress window to open the spreadsheet in Microsoft Excel.

2.3.6.2 Exporting Detail to PDF

This procedure is performed on the Oracle API Catalog home page.

2.3.6.2.1 Exporting from the Detail Page

You can export the asset details to PDF from the Detail page.

  1. Use Search or other means to locate the appropriate API.

  2. Click the PDF icon in the API detail.

  3. If prompted to do so, select a printing template from the list.

    If the Adobe Acrobat plug-in is installed, the browser opens the PDF. Otherwise, you are prompted to save or open the file.

2.3.6.2.2 Exporting from the Search Results List
  1. Perform an API search by entering search terms in the Search field.

    (Optional) Select a service type or published status from the lists as necessary to refine the search.

    Note:

    You must have the curator or admin roles to view the list with published status options in the search region.
  2. Select one or more APIs from the search results by placing a check in the check box that appears to the left of APIs listed in the Search Results.

  3. Select Export to PDF from the list above the list of APIs.

  4. Click Go.

  5. If the Adobe Acrobat plug-in is installed, the browser opens the PDF. Otherwise, you are prompted to save or open the file.

2.3.6.3 Exporting Asset Search Results to ZIP

When enabled, the Export to ZIP feature allows the export of asset information to a ZIP file, through a menu selection on the asset search results screen.

  • The Export to ZIP feature is available only to users with Administrator permissions.

  • Import/Export must be enabled. For more information, see the "System Settings Overview" chapter in the Oracle Fusion Middleware Administrator's Guide for Oracle API Catalog.

This procedure is performed on the Oracle API Catalog home page.

  1. Perform an asset search by entering keywords in the Search field. Select a service type or published status as necessary to refine the search.

    Note:

    You must have the curator or admin roles to view the list with published status options in the search region.
  2. Use the check boxes in the search results list to select the APIs to be exported to ZIP.

  3. Select Export to ZIP from the list.

  4. Click Go. The Export to ZIP progress dialog is displayed.

  5. When the export is complete, click Download to download the exported zip file. The File Download dialog is displayed.

  6. Select Open, Save, or Cancel, as appropriate.