Oracle by Example brandingDocumenting an API

section 0Before You Begin

This 10-minute tutorial shows you how to add documentation to an API in Oracle API Platform Cloud Service and use an Apiary API specification as the documentation for the API.

Background

When you publish an API in the Oracle API Platform Cloud Service Developer Portal, adding documentation is critical for application developers to understand what the API does and how it works.

You can create and publish documentation for an existing Apiary API. To accomplish this, you must link the existing API to the documentation in Apiary. You can then publish the API so that application developers know the purpose, features, and usage of the API. 

What Do You Need?

  • Access to an Oracle API Platform Cloud Service instance, with the application developer role.
  • An Apiary account.
  • An existing API in Apiary that you own. For this tutorial, you can use the Warranty Claim API as an example.
  • An existing API in Oracle API Platform Cloud Service.

section 1 Access the API in Management Portal

  1. Sign in to the Oracle API Platform Cloud Service Management Portal by entering a URL in the following format:

    https://instance-identityDomain.apiplatform.ocp.oraclecloud.com/apiplatform

    For example, https://apidemo-paasproducm.apiplatform.ocp.oraclecloud.com/apiplatform

  2. On the APIs page, select the Warranty Claim API from the list. Alternatively, in the Search By Name field, enter Warranty Claim, and then select the Warranty Claim API. 

section 2 Link Apiary and API Actions to the API

  1. On the Specification page, click Apiary.
    Specification's Page
    Description of the illustration specification.png
  2. If prompted, sign in to Apiary Portal.
  3. From the list of API projects, select the Warranty Claim project.
  4. Select the Use as API Documentation check box.
  5. Click Connect to link the Apiary Warranty Claim project as the specification and documentation for the API.
    Apiary Documentation page
    Description of the illustration apiary-documentation.png
  6. To verify that the Apiary project data is downloaded, make sure that a link with File: Warranty Claim appears under the Apiary button, and the API Actions are defined.
    Warranty Claim connected to the Apiary
    Description of the illustration apiary-link.png
  7. Click Save.

section 3Add Text for the Developer Portal API Overview

  1. On the API details page, select the Publication tab.
  2. In the Developer Portal API Overview section, click HTML.
    Developer Portal API Overview
    Description of the illustration devportal-html.png
  3. Click the Text tab.
  4. Enter a short, one-sentence description for the API.
    HTML Text tab
    Description of the illustration devportal-html-text.png
  5. Click OK.

section 4Configure the API Portal URL

  1. In the Enter the Portal name field, located under API Portal URL, enter the URL of the Oracle API Platform Cloud Service Developer Portal.
    API Portal URL
    Description of the illustration developer-url.png
  2. Click the tick mark tick mark.
  3. Click Save.

section 5 Publish the API to the Developer Portal

  1. Click Preview, to view the documentation.
  2. After you verify the API documentation, click Publish to Portal.

    Note: If you have already published to the portal and later make changes to the documentation or overview, then click Republish.

    Publish to Portal option
    Description of the illustration publish-portal.pn

section 6 Open the Developer Portal

  1. On the APIs page, select Warranty Claim.
  2. Click the link under API Portal URL, to see the documentation in the Oracle API Platform Cloud Service Developer Portal.
    Warranty Claim API in Developer Portal
    Description of the illustration launch.png
  3. Verify that the API opens on the Oracle API Platform Cloud - Developer Portal page.
    Warranty Claim API in Developer Portal
    Description of the illustration api-platform-cloud.png

more informationWant to Learn More?