6 Curating and Publishing Your APIs Using Oracle Service Bus

After creating your APIs, you must add metadata to and publish the API before it receives any traffic. This chapter describes curating and publishing WSDL-based SOAP and REST proxy services as APIs using the Oracle Service Bus Console, which is installed with API Manager.

The tasks described here are performed by users with the API Curator role.

Note:

API proxy services need to be created and activated before you begin the tasks in this chapter. See Creating Your APIs for more information.

The following topics are covered:

6.1 Editing the Metadata of an API

After creating a proxy service, you can add descriptive metadata that is displayed in an API detail page in the API Manager Portal.

API Consumers use this metadata to determine if an API is a good choice for their application and to test the API. Users with access to the Service Bus console can also evaluate this API using the metadata.

To edit the metadata of an API:

  1. From the Oracle Service Bus Console, open the Proxy Service Definition for the service you want to publish.
  2. Click the API tab. From the Overview region, click Edit, as shown in the following figure.
  3. Edit the metadata properties, as described in the following table:
    Element Description

    Overview

    Use this section to modify basic metadata associated with an API.

    Name

    Enter a name for the API

    Version

    Enter version information for the proxy service.

    Description

    Enter a detailed description of the functionality of an API.

    Tags

    Enter any tags you want to associate with the API. You can search for APIs using these tags in the Oracle API Manager portal.

    Deprecation Status

    Use this section to set options related to deprecating an API.

    Deprecated

    Select to deprecate the API.

    Description

    Enter text describing why the API was deprecated, including superceding versions, if any.

    References

    Use this section to add external documentation references or other information sources.

    Note: You are limited to a maximum of four references.

    Name

    Enter a name for the reference.

    URL

    Enter the URL for the reference.

    Security

    Use this section to add security information.

    Overview

    Enter an overview of the global security policies attached to this API.

    Note: Descriptions of individual security policies from OWSM are exposed to consumers on the API Details page.

    Test

    Use this section to add testing information.

    Test URL

    Enter a URL used to test the API.

    Tip:

    You can include usage instructions for the Test URL in the Description field in the Overview section or as an HTML reference in the Reference section.

  4. Click Save. The metadata for the API is now updated to reflect your changes in both the Oracle Service Bus Console and the API Manager Portal.

6.2 Understanding API Status

The status of an API determines whether it is hidden from or published to the API Manager Portal.

API status is set in the Status list in Publish Status region on the API tab, as shown in the following figure:

Description of GUID-3C482777-BF82-422E-8DD7-A09222AD88D0-default.png follows
Description of the illustration GUID-3C482777-BF82-422E-8DD7-A09222AD88D0-default.png

You can set the following status for an API:

  • Draft: Draft APIs are not published to the Oracle API Manager Portal and all requests to them are blocked. This is the default option.

  • Private: Private APIs are available for users with Developer privileges in Oracle Service Bus. Private APIs are not visible in the API Manager Portal and are unavailable to users with the API Consumer role. Making an API Private describes making an API private.

  • Published: Published APIs are published to consumers on the Oracle API Manager Portal. Publishing an API to the Oracle API Manager Portal describes publishing an API.

6.3 Making an API Private

You can make an API private if you want it to be available for users with Developer privileges in Service Bus. APIs marked private are not visible in the API Manager Portal and are unavailable to users with the API consumer role.

To make an API private:

  1. From the Oracle Service Bus Console, open the Proxy Service Definition for the service you want to make private.
  2. Click the API tab. From the Publish Status region, click Edit.
  3. From the Status list, select Private.
  4. Click Save. The API is now private.

6.4 Publishing an API to the Oracle API Manager Portal

Before making an API available to consumers through the API Manager Portal, you should decide whether it should be managed or unmanaged. You then change the status to Published to publish the API.

Tip:

Make sure that you have added metadata to the API, as described inEditing the Metadata of an API, before publishing it to the API Manager Portal.

6.4.1 Deciding if an API Should Be Managed or Unmanaged

Before publishing an API, you decide whether an API should be published as managed or unmanaged:

  • Managed APIs can only be invoked by passing the application's entitlement key as a header at runtime. Users must subscribe to an API to receive this key. Users attempting to invoke managed APIs without using the key will receive an error message.

  • Unmanaged APIs are not controlled at runtime and can be accessed without passing an entitlement key. Users can invoke these APIs without subscribing to them.

You select the Managed check box when you publish an API to make it managed, as described in Changing the Status of an API to Published. If you later decide that the API should not be published, deselect the Managed check box.

Note:

If you decide to make a previously managed API unmanaged, user requests to the API that include an application's entitlement key, which is required for managed but not unmanaged APIs, will ignore the X-API-KEY attribute in the header. The request is processed normally.

6.4.2 Changing the Status of an API to Published

You change the status of an API to published to publish it to the API Manager Portal.

To publish an API:

  1. From the Oracle Service Bus Console, open the Proxy Service Definition for the service you want to publish.
  2. Click the API tab. From the Publish Status region, click Edit.
  3. From the Status list, select Published.
  4. Select the Managed check box if you want this API to be managed.
  5. Click Save. The API is published to the API Manager portal.

    Note:

    Clicking the Clear All button in this region resets all fields to their default values. You must then click OK to confirm.

6.5 Hiding an API from the API Manager Portal

If you have published an API, but later decide that it should not be visible on the API Manager Portal and all requests to the API should be blocked, then you can set its status back to draft.

Note:

Deleting a proxy service from the Service Bus Console will also remove it from the API Manager Portal.

To change the status of an API to draft:

  1. From the Oracle Service Bus Console, open the Proxy Service Definition for the service you want to mark as Draft.
  2. Click the API tab. From the Publish Status region, click Edit.
  3. From the Status list, select Draft.
  4. Click Save. The API is now hidden from the API Manager Portal.

6.6 Deprecating an API

Deprecated APIs will remain published to the API Manager Portal. Users can view the details of, but cannot subscribe to, deprecated APIs.

You can provide details about why the API was deprecated, such as which API supersedes the deprecated version.

Note:

Users who have subscribed to an API before it is deprecated will still be subscribed to it. Requests to the API are processed normally.

To deprecate an API:

  1. From the Oracle Service Bus Console, open the Proxy Service Definition for the service you want to deprecate.
  2. Click the API tab. From the Overview region, click Edit.
  3. From the Deprecation Status section, select the Deprecated option.
  4. From the Deprecation Status section, enter a deprecation description into the Description field, as shown in the following figure. This description should include the reason the API is deprecated and any superceding versions.
  5. Click Save. The API is now marked as Deprecated in the API Manager Portal.

6.7 Next Steps

Next steps include discovering, testing, and using APIs.

See Using the Oracle API Manager Portal for more information.