Accessing API Documentation

Access API documentation.

Note: This information is to help app developers to access API documentation. For information on adding or generating API documentation, see API Documentation Maintenance.

Table of Contents

Authored API Documentation:

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 APIs > My APIs > choose 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 Community Manager 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

  1. Go to APIs > My APIs > choose API > Documentation. The main documentation page for the selected API is displayed.
  2. 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 Community Manager 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).

Generated API documentation: initial view

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.

Setup/Security 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 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.

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 (Default Theme).

Generated API documentation: expanded view

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 Petstore 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 Petstore API, addPet operation

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

  1. Click Setup, specify your app, and click Save. For detailed instructions, see Test Client: Setup (Authentication Settings).
  2. Click Security, choose settings and provide values, and click OK. For detailed instructions, see Test Client: Security 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.

How do I switch between Swagger 2.0 and Open API 3.0 formats in the generated documentation?

Valid in Version: 2019.1.5 and later

You can view the documentation for an API via the APIs > My APIs > choose API > Documentation tab. The documentation format might vary depending on the API, but by default, there is generated API documentation and you can switch between versions.

The feature set of what's supported between the Swagger 2.0 standard and the Open API 3.0 specification is of course a little different, so if you choose to view the documentation in one format/standard or another there will most likely be differences in the way the documentation is displayed. In all cases, you'll only see what's supported by the API.

The example below shows the difference if you view the Swagger Petstore API, addPet operation, in Swagger 2.0 or in OAS 3.0.

OAS 3.0 (default):

The example below shows the generated API documentation for the Add Pet operation from the sample Petstore API, a POST operation, in OAS 3.0. If you prefer to view in Swagger 2.0, click the Switch to Swagger 2 button.

Swagger 2.0:

The example below shows the generated API documentation for the same operation as above, in Swagger 2.0 format. Less information is displayed, because of differences between the two standards. If you prefer to view in OAS 3.0, click the Switch to Open API 3 button.

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.

Image Color Usage
HTTP POST Green HTTP POST
HTTP PUT Brown HTTP PUT
HTTP GET Blue HTTP GET
HTTP DELETE Red HTTP DELETE

Can I download the API specification?

Valid in Version: 2019.1.34 and later

On the API > Documentation page, you can download the API description document for the API, in OAS 3.0 format (the default) or Swagger 2.0.

If the API has two implementations, you have the option to choose Live or Sandbox, as shown below. The API description document is displayed in the browser.

API Documentation page, buttons

To download a Swagger 2.0 version, click Switch to Swagger 2 and then click Download.