API Documentation

Access API documentation.

Table of Contents

Authored API Documentation:

1. Does the platform provide API documentation?
2. How do I access the API documentation?

Generated API Documentation:

1. What is the generated API documentation?
2. How do I use the generated API documentation?

Authored API Documentation:

Does the platform provide API documentation?

Each API includes a set of reference documentation which is available via the My APIs > API Name > Documents tab. The specifics in terms of what documentation is offered vary from API to API.

In some cases, certain APIs, or portions of them, have restricted visibility. In those cases, you would need to be invited to have visibility of those properties and their associated documentation. However, in many cases, the API documentation is publicly shared. You can locate it by using the Search feature in the platform.

A typical API documentation set might include the following sections:

• Overview—A summary of the API functionality, links to reference documentation for the operations, and a Getting Started section that illustrates key information and steps for using the API.
• Developer Guide—Reference documentation for each API operation (method). A typical organization might include use cases, URI (endpoint), sample request, request parameters, sample response, response parameters, and error handling information.
• Users Guide—Instructions for how to connect to the API, and ideally a walkthrough of API use cases.

Back to top

How do I access the API documentation?

To access the API documentation:

1. Select My APIs > API Name > Documents. The Documents page for the selected API displays.
2. Review the documentation, clicking through to additional pages as needed.
3. Note: If there is no authored API documentation, the generated API documentation will display. See What is the generated API documentation? below.

Back to top

Generated API Documentation:

What is the generated API documentation?

APIs on the developer portal usually have some generated API documentation that the portal creates dynamically from the API definition. This generated API documentation allows you to experiment with the API.

Initial view

The image below shows an example of the initial view of the generated API documentation for the Swagger Petstore API (a subset of operations).

This gives you a top-level view of the API. From here, you can see which operations are available and choose which one you want to try out.

Navigation controls available:

• Show/Hide: Shows or hides the entirety of the API documentation including the list of operations.
• List Operations: Shows only the summary list of operations, as shown above.
• Expand Operations: Shows the detailed view of all operations.
• Expand individual operation: Click anywhere in the area for a specific operation to expand or collapse the detail for that operation.

Security/Config buttons

Depending on how the specific API you're using is set up, you might need to click the buttons at the top to identify your app to the API and choose your connection preferences, including OAuth grant type if you want to test the API's OAuth support. Once you set these values, they apply for any operations you use for the entirely of your session while you are in the Documents window:

• Security button: specify environment and endpoint, and choose your app. These are the same security settings used in Test Client. For detailed instructions, see Test Client: Security Settings.
• Config button: Specify values required by any policies associated with the API. For example, for OAuth, you'll need to provide client credentials to identify the app. These are the same config settings used in Test Client. For detailed instructions, see Test Client: Config Settings.

 

Detailed view

The image below shows an example of the detailed view of the generated API documentation for the Swagger Petstore API, if you click one operation.

Back to top

How do I use the generated API documentation?

In the generated API documentation, you can click around to see what operations the API offers, what values it supports, and in general how it works. You can send actual messages and receive responses.

Unless the API supports anonymous access, you'll first need to click the two buttons at the top right, first Security and then Config, to specify values to identify with the API.

Once that's done, you can try out the operations.

The example below, for a partial implementation of the Swagger Petshop API, gives the exact steps you'll need to take to get a successful response. This is just one scenario. Each API is different.

Sample scenario: Swagger Petshop API, addPet operation

To get a successful response for this API, you'd need to complete the following steps:

1. Click Security, specify your app, and click Save. For detailed instructions, see Test Client: Security Settings.
2. Click Config, choose settings and provide values, and click OK. For detailed instructions, see Test Client: Config Settings.
3. Expand the section for the addPet operation.
4. Paste the payload JSON (see http://petstore.swagger.io, Pet, POST /Pet).
5. Set the request header, if needed, to application/json.
6. Click Invoke.

   The response JSON should be displayed.

If there are any issues, refer to the Test Client troubleshooting section: Troubleshooting in Test Client.

Back to top