OpenAPI Documentation
  • 28 Jun 2024
  • Dark
    Light
  • PDF

OpenAPI Documentation

  • Dark
    Light
  • PDF

Article summary

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
01_OpenAPI_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
02_OpenAPI_searchFilter

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
03_OpenAPI_requestExample

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”
04_OpenAPI_executeButton

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
05_OpenAPI_responseExample

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
06_OpenAPI_responseSchema

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.


Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.