Publishing APIs
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.
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.
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.
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.
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.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:
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 thehttp://
in the address bar to https://
and reload. The content displays correctly.