Accessing API Documentation
Access API documentation.
API Platform Version: 8.1 and later
Table of Contents
- What is the generated API documentation?
- How do I use the generated API documentation?
- What is the color coding on the generated API documentation?
Authored API Documentation:
Does the platform provide API documentation?
Each API can include a set of reference documentation which is available via the My APIs > API > Documentation 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. See Using Search in the Developer Portal.
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.
How do I access the API documentation?
To access the API documentation:
- Select My APIs > API > Documentation. The main documentation page for the selected API displays.
- Review the documentation, clicking through to additional pages as needed.
- Note: If there is no authored API documentation, the generated API documentation will display. See What is the generated API documentation? below.
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.
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.
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 Documentation window:
- Setup 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: Setup (Authentication Settings).
- Security 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: Security Settings.
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.
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 Setup and then Security, 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:
- Click Setup, specify your app, and click Save. For detailed instructions, see Test Client: Setup (Authentication Settings).
- Click Security, choose settings and provide values, and click OK. For detailed instructions, see Test Client: Security Settings.
- Expand the section for the addPet operation.
- Paste the payload JSON (see http://petstore.swagger.io, Pet, POST /Pet).
- Set the request header, if needed, to application/json.
- Click Invoke.
The response JSON should be displayed.
If there are any issues, refer to the Test Client troubleshooting section: Troubleshooting in Test Client.
What is the color coding on the generated API documentation?
When you run operations in Test Client, the HTTP code for the response message is color coded as shown below. For an example, see What is the API Designer?
These color codes are also used in the generated API documentation. For an example, see Initial View above.