Automated API Documentation

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.

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.

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.

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

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

• Request URL
• Request Method
• Request Headers
• Request Body
• Response Status
• Response Headers
• Response Data

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:

• POSTMAN: Create a Postman collection that can be imported into the postman application.
• HTML: Generate a static self-contained HTML document that can be deployed to a web server.
• PRINT: Generate a printable document. Send the document directly to a printer, or optionally save the document as a PDF document.