Skip to main content

Getting Started with the Public API

Authentication

When exercising the API in Swagger UI, users can authenticate using their VirtualWisdom 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 VirtualWisdom 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 VirtualWisdom.

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 VirtualWisdom 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 VirtualWisdom, you can access the Swagger UI using the following URL, replacing IPADDRESS with the IP address or FQDN of your VirtualWisdom Appliance or Virtual Edition instance.

https://IPADDRESS/api/sdk/p/index.html

You'll see a page that looks like the following.

vw-api-1.png

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 VirtualWisdom, 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

vw-api-2.png

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.

vw-api-3.png

Endpoint Definitions

There are currently four, top-level endpoints. They are:

vw-api-4.png

Other related endpoints, or aliases, resolve to these top-level endpoints. For example, the aliases related to /api/sdk/p/2/schema are:

vw-api-5.png

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.

vw-api-6.png
vw-api-7.png

Warning

Case matters when specifying endpoint URLs and payload. In particular, VirtualWisdom 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.