Getting Started with the Public API
Authentication
When exercising the API in Swagger UI, users can authenticate using their IPM user ID and password credentials.
To access the API from another application, such as cURL or Postman, users must authenticate using a bearer token in an authorization header that is sent as part of each request. Refer to the IPM Administrator Guide for information about generating API tokens. The following is an example of an authorization header: authorization: bearer MmQyYWYzMzdhNjY4YWNkYzpvU1laUTNQSDF5Vkk= . The long hash after bearer as shown above is a sample token generated by IPM.
Note
The vw-admin role is required to generate API tokens. However, users with either the vw-user or vw-readonly roles can access the API.
Accessing Endpoint Documentation
There are two methods for accessing API endpoint documentation. The first is via the Swagger UI. The second is to specify a help query parameter to specific endpoints.
Accessing Endpoint Documentation via the Swagger UI
Note
Swagger documentation is only available directly from IPM for releases 7.1.0 and higher. For earlier supported releases, the Swagger content and also the YAML content discussed below will be made available on Egnyte, Virtana's official software distribution tool.
To view the Swagger content, download the file called, for example, PublicAPI_1.2.2_OfflineSwagger.zip, unzip it, and then open the index.html file in a browser.
After authenticating with IPM, you can access the Swagger UI using the following URL, replacing IPADDRESS with the IP address or FQDN of your IPM Appliance or Virtual Edition instance.
You can access the Swagger Documentation from the UI by navigating to Administrator > API Documentation.
You'll see a page that looks like the following.
A few things to note:
In the upper left-hand corner of the page there is a link that you can click on to retrieve the OpenAPI YAML file, which can be used in third-party applications like Postman.
On the middle right-hand side of the page there is an Authorize button, which you can click on to input an API token. As you are already authenticated with IPM, this is an optional step.
Beginning in the bottom two thirds of the page there are endpoint definitions. Clicking on the down arrow at the right side of each endpoint definition will reveal detailed information about that specific endpoint. Note in particular the endpoints under the Getting Started heading. Explore these endpoints first to get familiar with the API before exploring others.
The Swagger UI is interactive, allowing the user to try out various endpoints.
Accessing Endpoint Documentation Using the Help Query Parameter
You can access additional help information for each information using the help URL query parameter. Enter the following URL for a summary of supported endpoints.
https://IPADDRESS/api/sdk/p/2?help
Each link contains more detailed help for each of the listed endpoints and also a list of hierarchically related endpoints. For example, the URL
https://IPADDRESS/api/sdk/p/2/inventory?help
will display information about the inventory endpoint as shown below.
Endpoint Definitions
There are currently four, top-level endpoints. They are:
Other related endpoints, or aliases, resolve to these top-level endpoints. For example, the aliases related to /api/sdk/p/2/schema are:
For the aliased endpoints, there's a URL parameter called "example" which, when included in the URL--it can either be empty (no value) or set to true, will return JSON information containing the URL and payload of the related top-level endpoint.
Examples
Each endpoint has examples of common use cases in the Request Body section as shown below. Selecting an example from the drop-down menu will show representative sample JSON payload for that example.
Warning
Case matters when specifying endpoint URLs and payload. In particular, IPM display labels and properties must be written using the proper case or no results will be shown.
Rate Limiting and Performance
Rate limiting is applied to every endpoint as part of each request. For more specific information about these limits and their performance implications, please consult the Swagger documentation.