Publish 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

• Configure the Developer Portal URL for an API

• Add Overview Text for an API

• Document an API

• Publish an API to the Developer Portal

Configure the Developer Portal URL for an API

Before publishing to the Developer Portal, each API must 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.

An 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 the 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.

To configure the Developer Portal URL for an API:

1. From the APIs List page, select the API that you want to publish.
2. Click the (Publication) tab.
3. In the API Portal URL field, enter the path at which this API will be discoverable in the Developer Portal. This is also called the API’s vanity name.
   For example, if you enter creditcheck, then when the AP is published, its details pageis visible at https://<host>:<port>/developers/apis/creditcheck.
4. Click Save.
   

Add 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.

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

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. The entire web page at the URL you enter appears in an iframe in the Developer Portal.
5. Click Save.
   

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

Document 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.

Topics

The API Request URL is not displayed in the Developer Portal. You should include it in the API’s documentation so Application Developers know where to send requests.

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

• Add Oracle Apiary Documentation to an API

Add 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.
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. The entire web page at the URL you enter appears in an iframe in the Developer Portal.
5. Click Save.
   

Add 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.

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 the API to which you want to add Apiary documentation.
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.

Publish an API to the Developer Portal

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

When you publish an API, you make its details page available on the Developer Portal. The details page displays basic information about the API, an overview describing the purpose of the API, and documentation for using the API.

Note:

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

To publish an API to the Developer Portal:

1. From the API List page, select the API you want to publish.
2. Click the (Publication) tab.
3. Enter a directory name in the API Portal URL field, if necessary. 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.
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 allow 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.