OpenAPI Documentation

In the 2023.1 feature release, Itential added support for generating a feature-complete OpenAPI 3.0 Specification for Itential Automation Platform (IAP) that includes all API routes within IAP, including the routes that were previously hidden in pronghorn-core as well as the routes in adapters and custom applications. We have also enabled dynamic output with a "Try it out" feature within a Swagger-based UI. This page documents OpenAPI documentation in IAP and provides guidance on how it is used.

Authorization

It is important to know that the “Try it out" feature is controlled by authorization settings based on the current user. If you do not have permission to call a specific API, the "Try it out" feature will return a 401 error, but you will be able to see the documentation for the route. As shown in Figure 1 below, it is possible to log in with a token or username/password separately when making these API calls, if desired.

Figure 1: Authorizations

Search Filter

Itential has also implemented a simple filter to make it easier to find the application or adapter specific to the API documentation you wish to see. As shown in Figure 2, simply input a short string (e.g., “adapter”) as the filter to generate your search results.

Figure 2: API Search Filter

Available Parameters

When you select an individual method, you can view all the available parameters for that method as defined in the pronghorn.json file for the relevant application. This may also include default examples, such as when a route takes in a request body. In Figure 3, some of the expected inputs for the getAdapterModelTypes API are shown. You can also see they are not required parameters.

Figure 3: API Request Example

To call the “Try it out” feature, click the Execute button after entering all the relevant inputs (Figure 4).

Figure 4: Execute Button for “Try it out”

API Response

If the user making the request has access to the API, the full response will be returned to the user (Figure 5). In addition, information about response headers along with the time it took to execute the response will be presented.

Figure 5: API Response Example

Response Schema

Also documented is the expected schema for the API method and any error codes that may occur. Currently, the only error code that returns for all methods is a 500 response. Figure 6 shows the expected schema for the method when it returns a 200 response, as well the models type application/json.

Figure 6: Response Code and Schema

Custom Applications

To ensure all APIs are included within the UI, all custom applications must have valid JSON schemas defined for each API method. While the accuracy of the JSON schema matching the method’s input or output is not enforced, ensuring that it does not have any errors according to JSON schema standards will guarantee it is included in the OpenAPI document. An error will be logged for any methods that are marked as invalid, and they will not be viewable from the UI.

OpenAPI Specification

The OpenAPI 3.0 Specification is available through GET /help/openapi/. The API returns a JSON that conforms to the OpenAPI 3.0 Specification. The required query parameter URL is the base URL of IAP in which the user wants the specification returned from.

For example:

GET /help/openapi/?url=http://yourhostname.com:3000

The returned JSON can be viewed in a browser, or the result can be copied to a different viewing document.