Publishing APIs

Use the Publication page to publish APIs to the Developer Portal. On this page you provide general details about and provide detailed documentation references for your API. After publication, Application Developers use the Developer Portal to discover, evaluate, register, and consume your published APIs.

Topics

• Configuring an API’s Developer Portal URL

• Adding Overview Text for an API

• Documenting an API

• Publishing an API to the Developer Portal

Configuring an API’s Developer Portal URL

Before publishing to the Developer Portal, each API has to be configured with its own unique Vanity Name. A vanity name is the URI path of an API’s details page when it is published to the Developer Portal.

For example, if your Developer Portal URL is http://example.com:7201/developers/apis/, you can publish the details page for your API to http://example.com:7201/developers/apis/Energy, where Energy is the vanity name you enter in the Management Portal.

To configure an API’s Developer Portal URL:

1. From the APIs List page, select the name of the API that you want to edit.
2. On the Publication tab, enter the path at which this API will be discoverable in the Developer Portal in the API Portal URL field. This is also called the API’s vanity name.
   For example, enter creditcheck. When published, the details page for this API is visible at https://<host>:<port>/developers/apis/creditcheck.

   Note:

   An API’s vanity name must be unique, regardless of case. You can’t have APIs with vanity names of Creditcheck and creditcheck. You must enter the vanity name exactly (matching case) in the URL to navigate to an API’s details page in the Developer Portal. For example, navigating to https://<host>:<port>/developers/apis/Creditcheck opens the page for an API with a vanity name of Creditcheck; https://<host>:<port>/developers/apis/creditcheck doesn’t open this page and returns a 404 because the segment in the URL does not match the vanity name exactly.

   Only valid URI simple path names are supported. Characters such as “?”, “/”, and “&” are not supported in vanity names. Test_2 is a supported vanity name, but Test/2 is not.

3. Click Save.
   

Before publishing an API, you should also configure it’s overview text and documentation references. See Adding Overview Text for an API and Documenting an API.

The API is not visible on the Developer Portal until you publish it. See Publishing an API to the Developer Portal.

Adding Overview Text for an API

You can provide overview text for an API, describing its features and other information a developer should know about its use, in either HTML or Markdown.

You can upload a file, enter text manually, or provide a link to HTML or Markdown to use as overview text. This text appears on the API’s detail page in the Developer Portal.

Note:

Detailed use information for an API, such as an API’s resources and methods, are better described in documentation references. See Documenting an API.

To add overview text for an API:

1. On the APIs List page, select the API to which you want to add overview text.
2. Click the Publication tab.
3. From the Developer Portal API Overview section, click HTML or Markdown, depending on the format of your overview text.
4. Do one of the following:
   1. To add overview text stored in a file, click the File tab, and then click Choose File. Navigate to and select the file on your local disk that contains the overview text you want to display. After selecting your file and closing the file browser, Click OK.
   2. To manually enter overview text, click the Text tab, and then enter HTML or Markdown overview text. Click OK.
   3. To display overview text from a web page, click the Link tab, and then enter the URL of the overview text page you want to display. Click OK.

      Note:

      The entire web page at the URL you enter appears in an iframe in the Developer Portal.

5. Click Save.
   

The overview text is added to the API’s detail page in the Developer Portal.

You must (re)publish this API to the Developer Portal before this text is visible. See Publishing an API to the Developer Portal.

Documenting an API

Publishing an API allows application developers to discover and register applications to the API. API publication and deployment are two separate activities; API publication allows consumers with the correct grants to access the API web page and API deployment makes the API endpoint accessible. Use the topics in this section to learn more about publishing API details to the Developer Portal.

Important:

The API Request URL, configured in Configuring the API Request URL, is not displayed in the Developer Portal. You must list it in the API’s documentation so Application Developers know where to send requests.

Topics

• Adding HTML, Markdown, or Web Page Documentation to an API

• Adding Oracle Apiary Documentation to an API

Adding HTML, Markdown, or Web Page Documentation to an API

You can provide HTML or Markdown documentation by uploading a file, manually entering text, or providing a URL to the documentation resource. After you have added the documentation, it appears on the Documentation tab of the API detail page in the Developer Portal.

To add HTML, Markdown, or web page documentation to an API:

1. From the APIs List page, select the API to which you want to add documentation.
2. Click the Publication tab.
3. From the Documentation section, click HTML or Markdown, depending on the format of your documentation. See Adding Oracle Apiary Documentation to an API if you want to add documentation from Oracle Apiary.
4. Do one of the following:
   1. To add documentation stored in a file, click the File tab, and then click Choose File. Navigate to and select the file on your local disk that contains the documentation text you want to display. After selecting your file and closing the file browser, Click OK.
   2. To manually enter documentation text, click the Text tab, and then enter HTML or Markdown text. Click OK.
   3. To display documentation text from a web page, click the Link tab, and then enter the URL of the overview text page you want to display. Click OK.

      Note:

      The entire web page at the URL you enter appears in an iframe in the Developer Portal.

5. Click Save.
   

Adding Oracle Apiary Documentation to an API

Use this procedure to add Oracle Apiary documentation to an API. Adding documentation to the API can help users understand its purpose and how it was configured.

Note:

Swagger or API Blueprint documentation can only be added to an Oracle Apiary Pro account. To add documentation, the team must have ownership of the API in Oracle Apiary. API definitions owned by personal accounts cannot be used. To transfer ownership of an API from a personal account to a team account, see the Oracle Apiary documentation.

To add Oracle Apiary documentation to an API:

1. On the APIs List page, select an API.
2. Click the Publication tab.
3. Click the Apiary button.
   The Apiary Documentation dialog appears, allowing you to browse documentation on Oracle Apiary.
4. Select an API Project and then click Connect.
5. Click Save.
   

If you have previously published the API, you must republish it to see the Apiary specification.

Publishing an API to the Developer Portal

Publish an API to the Developer Portal when you want application developers to discover and consume it.

Each published API has a details page on the Developer Portal. This page displays basic information about the API, an overview describing the purpose of the API, and documentation for using the API. This page is not visible on the Developer Portal until you publish it.

To publish an API to the Developer Portal:

1. From the API List page, click the name of the API you want to publish.
2. Click the Publication tab.
3. Ensure that the vanity name is present in the API Portal URL field. See Configuring an API’s Developer Portal URL if you haven’t entered a vanity name yet. Click Save if you have made any changes on this page.
4. (Recommended) Ensure that you’ve added overview text and documentation references. You can publish an API without providing these, but Application Developers need this information to know how to use your APIs.
   If you haven’t added these yet, see Adding Overview Text for an API and Documenting an API.

   Important:

   The API Request URL, configured in Configuring the API Request URL, is not displayed in the Developer Portal. You must list it in the API’s documentation so Application Developers know where to send requests.

5. Click Publish to Portal.

The API is now visible on the Developer Portal. You can view its details page at the URL displayed in the API Portal URL field or by clicking the (Launch Developer Portal in another browser window) icon next to the URL.

Note:

The HTML documentation is embedded in an iframe in the Developer Portal. Due to security constraints, a few browsers do not let an HTTP frame to be embedded into an HTTPs frame. They neither load the content nor give an error message. If the content does not show, change the http:// in the address bar to https:// and reload. The content displays correctly.