Automated API Documentation

Sample view of automatically generated API documentation for a project.

Instalink automatically generates documentation for all endpoints (LISTEN actions). Each Instalink project has its own corresponding documentation. The automated API documentation can be accessed by selecting "Docs" from the main menu of the project management screen.

Image example of button to view project documentation.

All top-level LISTEN actions are automatically included in the generated documentation. By default, the documentation includes details concerning the endpoint's URL and request method. A Data Flow Description, which describes each action that the data flow performs, is also automatically generated.

Additional documentation can be created for the endpoints. This includes detailed descriptions of the data flow, request parameters, and call examples.

Creating a Custom Description

To add a description to an endpoint, open the project in the project manager. Then select the desired LISTEN action. Navigate to the "Endpoint Documentation" subsection and edit the "Documentation HTML" property. HTML is permitted.

Creating a custom description for the endpoint.

Defining Endpoint Parameters

Endpoint parameters can be documented by navigating to the "Endpoint Form" subsection of a LISTEN action. All parameters defined here will also appear in the endpoint documentation. Edit the "Parameter Documentation" property to include additional details about the parameter. HTML is permitted.

Defining an endpoint parameter

Creating Endpoint Examples

Any inbound request record can be used to generate an example of the endpoint. To automatically generate an example, open an inbound request record and select "Create Documentation Example".

Image of Button to generate an example from an inbound request record.

Give the example a title and detailed description. The subsequent form automatically generates the details of the request including:

IMPORTANT: Be sure to scrub any potentially sensitive information from the data before saving the example. This may include access tokens, names, addresses, usernames, passwords, or other identifiers. The API documentation is likely to be made public so be sure that only information that can be made public is included.

Also be sure to truncate request and response data so that it only as long as it needs to be. For example, don't create an example that includes 100 records in the data when just 1 record succinctly conveys the behavior of the endpoint.

Open up a LISTEN action and navigate to the "Records" subsection and click the "Examples" link to view or modify previously created examples for an endpoint.

Exporting API Documentation

The API documentation as shown in the Instalink administration panel can only be accessed by an authenticated user with permission to view the project. However, it is possible to export the documentation to share it with external stakeholders. The export options appear at the top of the API documentation view. These options include the following: