- 28 Jun 2024
-
DarkLight
-
PDF
OpenAPI Documentation
- Updated on 28 Jun 2024
-
DarkLight
-
PDF
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.