The following topics will instruct you how to connect to the REST API and authorize your access, and how to control and sort the data that the REST API returns.

Each Veeam Plug-in for Nutanix AHV REST API-exposed entity has a resource representing it. To get a resource representation, request its URL.

Veeam Plug-in for Nutanix AHV 7 REST API requests use the following base URL format:

https://<hostname>/api/<version>

where:

• <hostname> is a public IPv4 address or DNS hostname of the Veeam Plug-in for Nutanix AHV backup appliance.
• <version> is an API version.

The current version is v7.

To get a collection of Veeam Plug-in for Nutanix AHV REST API resources, request the base URL followed by a resource collection endpoint. For example:

https://127.0.0.1/api/v7/jobs

To get a representation of an individual resource, enter a resource identifier after the resource collection endpoint. For example:

https://127.0.0.1/api/v7/jobs/3ad6270a-c42d-4925-aa48-9cbfc80100a6

The resource identifier is represented by the id property of the resource from the collection. For example:

[
  {
    "id": "83238f03-a894-497c-bf4d-7930f328f22a",
    "name": "Mail Server Daily Backup Job",
    ...
  },
  
  {
    "id": "3ad6270a-c42d-4925-aa48-9cbfc80100a6",
    "name": "Media Server Weekly Backup Job",
    ...
  }
]

The Veeam Plug-in for Nutanix AHV REST API is available in multiple versions. All existing Veeam Plug-in for Nutanix AHV REST API versions are supported. The API version must be specified in the request URL as described in Resource URLs. The current API version is v7.

The Veeam Plug-in for Nutanix AHV REST API is backward-compatible with client applications that were created using earlier versions of the REST API specification. This means that you can use any of the supported REST API specifications to perform operations with Veeam Plug-in for Nutanix AHV resources if the specification version has been released earlier or with the product version installed on the backup appliance:

To start working with the Veeam Plug-in for Nutanix AHV REST API, users must first authenticate themselves and get authorization to make requests. Veeam Plug-in for Nutanix AHV REST API authorization process is based on the OAuth 2.0 Authorization Framework and involves obtaining an access token and a refresh token.

• Access token is a string that represents authorization issued to the client and that must be used in all requests during the current logon session.
• Refresh token is a string that represents authorization granted to the client and that can be used to obtain a new access token if the current access token expires or becomes lost.

The Veeam Plug-in for Nutanix AHV REST API access token expires in 30 minutes, refresh token expires in 24 hours.

The authorization process involves the following procedures:

1. Requesting authorization.
2. Using the refresh token.
3. Performing logout.

The Veeam Plug-in for Nutanix AHV REST API accepts the password grand type to authenticate a Veeam Plug-in for Nutanix AHV user.

To obtain authorization tokens, a user sends the HTTP POST request to the api/v7/token endpoint.

The request body must contain the grantType parameter with the specified password value and the credentials of a Nutanix AHV backup appliance administrator.

A successfully completed operation returns the 200 response code. In the response body, Veeam Plug-in for Nutanix AHV returns an access token, a refresh token and expiration time of each token. The user inserts the access token in headers of further requests to the Veeam Plug-in for Nutanix AHV REST API. The refresh token must be saved locally.

To learn how to authorize your access using the Password grant type, see the example below. Alternatively, you can use the Swagger UI.

Example

To obtain an access token and a refresh token, a user sends the HTTP POST request to the api/oauth2/token endpoint.

In the request body, the user specifies the following parameters:

• grantType — the password value must be specified for this parameter.
• userName and password — credentials used to access the server; in this example, administrator and Password1 are used.

Request:
POST https://127.0.0.1/api/oauth2/token

Request Body:
grantType=Password&userName=administrator&password=Password1

The server sends a response in the following format.

Response:
200

Response Body:
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsJW3FHfvEMyes7h8gWruHtqc...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqd...",
  "accessTokenExpiresAt": "2022-11-01T13:25:33.446773Z",
  "refreshTokenExpiresAt": "2022-11-02T12:55:33.4468048Z"
}

To obtain a new pair of tokens in case the access token expires or becomes lost, a user sends the HTTP POST request with the refresh token in the request body to the api/oauth2/token endpoint. A successfully completed operation returns the 200 response code and a new pair of tokens in the response body.

Example

To obtain an access token and a refresh token, a user sends the HTTP POST request to the api/oauth2/token endpoint.

In the body of the request, the user specifies the following parameters:

• grantType — to refresh the token, it is required that the refreshToken value must be specified for this parameter.
• refreshToken — the previously saved refresh token.

Request:
POST https://127.0.0.1/api/oauth2/token

Request Body:
grantType=RefreshToken&refreshToken=eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0Qz...

The server sends a response in the following format.

Response:
200

Response Body:
{
  "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJuYmYiOjE1ODYyNTU3ODMsImV4cCI6MTU4NjI1NjY4MywiaWF0IjoxNTg2MjU1NzgzLCJhdWQiOiJhY2Nlc3MifQ.nDUwV...",
  "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJ0b2tlbl9pZCI6ImI5MjJhNGJiLTJmY2YtNGMwZi1hZGMxLTg2M2I4YzY1MzkxMiIsInNob3J0X3Rlcm1fZXhwaXJhdGlv...",
  "accessTokenExpiresAt": "2022-11-01T13:43:43.7826152Z",
  "refreshTokenExpiresAt": "2022-11-02T13:13:43.7826277Z"
}

To log out, a user sends the HTTP POST request to the api/oauth2/logout endpoint. A successfully completed operation returns the 204 response code.

Example

To log out, a user sends the HTTP POST request to the api/oauth2/logout endpoint.

Request:
POST https://127.0.0.1/api/oauth2/logout

The server sends a response in the following format.

Response:
204

To perform operations with Veeam Plug-in for Nutanix AHV entities using the REST API, you can use the following standard HTTP methods:

• GET — retrieves information about a resource or collection.
• POST — creates a new resource in a collection or activates a resource action.
• PUT — makes changes to a resource.
• DELETE — removes a resource from a collection.

To control the amount and order of data that the Veeam Plug-in for Nutanix AHV REST API returns for a resource or collection, you can use the following query parameters:

• Offset Parameter
• Limit Parameter
• Sort Parameters
• Filter Parameters

Query parameters are part of a URL. The question mark ? separates query parameters from a resource collection endpoint.

The offset query parameter is used to exclude from a response the first N items of a resource collection.

For example, to return a list of sessions starting from the third one in the /sessions collection, send the following request:

GET https://127.0.0.1/api/v7/sessions?offset=2

You can combine the limit and the offset query parameters to request a particular set of items. Note that the offset parameter is applied before the limit parameter, regardless of the parameter position in the request. That is, top results are selected from a collection where a set of items is already excluded.

The Veeam Plug-in for Nutanix AHV REST API returns resources in the default order based on its own semantics. To sort or filter a collection before excluding results, use the sort or filter query parameters. Note that the sort and filter parameters are applied before the offset parameter, regardless of their position in the request. That is, a collection is first filtered or sorted, and then the top results are excluded.

The limit query parameter is used to specify the maximum number of items of a resource collection to return in a response.

For example, to return only the first 3 VMs in the /protectedVms collection, send the following request:

GET https://127.0.0.1/api/v7/protectedVms?limit=3

The Veeam Plug-in for Nutanix AHV REST API returns resources in the default order based on its own semantics. To sort or filter a collection before excluding results, use the sort or filter query parameters. Note that the sort and filter parameters are applied before the limit parameter, regardless of their position in the request. That is, a collection is first filtered or sorted, and then the top results are excluded.

The sort query parameter is used to sort items of a resource collection in a response. Some resource properties of Veeam Plug-in for Nutanix AHV REST API schemas can be used as parameter values for the sort query parameter.

The parameter accepts the array data type. To sort a resource collection, use the sort query parameter in the following format:

GET https://127.0.0.1/api/v7/<endpoint>?sort=[{"property":"<property>","direction":"<direction>","collation":"<collation>"}]

where:

• endpoint is a resource collection endpoint.
• property is the searched property name.

• direction is a direction specifier. The following values are available:

  • ascending
  • descending

• collation is the type of rules that determine how sorted values are compared to each other. The following types are available:

  • ordinal — compare strings symbol-by-symbol
  • ignorecase — compare strings symbol-by-symbol ignoring character case
  • lexicographic — compare words with words and numbers with numbers

  The default value is ordinal.

For example, to sort items of the /sessions resource collection by start time where the sessions is located in the descending order, send the following request:

GET https://127.0.0.1/api/v7/sessions[{"property":"startTimeUtc","direction":"descending","collation":"ordinal"}]

Some resource properties of Veeam Plug-in for Nutanix AHV REST API schemas can be used as filter query parameters. Filter query parameters are used to filter items of a resource collection to return a subset of resources in a response. The subset includes only those resources that satisfy parameter value specified in the query.

To filter a resource collection use the filter query parameter in the following format:

GET https://127.0.0.1/api/v7/<endpoint>?filter=[{"property":"<property>","operation":"<operation>","collation":"<collation>","value":"<value>"}]

where:

• endpoint is a resource collection endpoint.
• property is the searched property name.

• operation is a relational or logical operator.

• collation is the type of rules that determine how specified values are compared with resource property values. The following types are available:

  • ordinal — compare strings symbol-by-symbol
  • ignorecase — compare strings symbol-by-symbol ignoring character case
  • lexicographic — compare words with words and numbers with numbers

  The default value is ordinal.

• value is a resource property value.

The Veeam Plug-in for Nutanix AHV REST API supports the following operators:

To group multiple filter expressions, you can include them into a grouping expression. A grouping expression includes the following elements:

• operation is a relational or logical operator.
• items is an array of filter expressions.

A grouping expression has the following format:

GET https://127.0.0.1/api/7/<endpoint>?filter=[{"operation":"<operation>","items":[{"property":"<property>","operation":"<operation>","value":"<value>","collation":"<collation>"},{"property":"<property>","operation":"<operation>","value":"<value>","collation":"<collation>"}]}]

To combine filter expressions you can use the following operators:

Example

For example, to return a list of session of backup jobs with the Success, Failed or Canceling status, send the following the request:

GET https://127.0.0.1/api/v7/sessions?filter=[{"operation":"and","items":[{"operation":"in","collation":"ordinal","property":"status","value":["Success","Failed","Canceling"]},{"operation":"in","collation":"ordinal","property":"sessionType","value":["BackupVmJob"]}]}]

To start working with the Veeam Plug-in for Nutanix AHV REST API, you can use any client application that supports the HTTPS protocol.

The Veeam Plug-in for Nutanix AHV REST API is additionally available through the Swagger UI, a tool that you can use to evaluate and explore capabilities of the REST API. The Swagger UI visually presents API specification files and allows you to work with resources.

All resources and methods are expandable. When you expand a method, you get a full description of available parameters and an automatically generated example. You can also send requests and see response messages.

To access the Swagger UI for the Veeam Plug-in for Nutanix AHV REST API, in a web browser, navigate to the following URL:

https://<hostname>/swagger/index.html

where <hostname> is a public IPv4 address or DNS hostname of the Veeam Plug-in for Nutanix AHV backup appliance.

In the Select a definition field, select the version and revision of the Veeam Plug-in for Nutanix AHV REST API.

Veeam Plug-in for Nutanix AHV REST API authorization with the Swagger UI involves the following procedures:

1. Obtain an access token and a refresh token:

   1. On the Veeam Plug-in for Nutanix AHV public API page, expand the Token resource and click POST api/oauth2/token.

   2. In the expanded method window, click Try it out.

      

   3. From the grantType drop-down list, select Password.

   4. In the userName and password fields, specify the credentials of a user created in Veeam Plug-in for Nutanix AHV.

   5. Click Execute.

      

      Wait for the response from the server. A successfully completed operation returns the 200 response code. In the response body, Veeam Plug-in for Nutanix AHV returns an access token, a refresh token, and the expiration time of each token.

      

   6. Save the access and refresh token locally for further use.

2. Authorize your access in the Swagger UI:

   1. At the top right corner of the Veeam Plug-in for Nutanix AHV public API page, click Authorize.

      

   2. In the Available authorizations window, insert the access token saved locally in the Value field. Use the Bearer <access_token> format.

      

   3. Click Authorize.

3. When the access token expires, use the refresh token:

   1. On the Veeam Plug-in for Nutanix AHV public API page, expand the Token resource and click POST api/v7/token.

   2. In the expanded method window, click Try it out.

   3. From the grantType drop-down list, select RefreshToken.

   4. In the refreshToken field, insert the refresh token saved locally, and click Execute.

      

      Wait for the response from the server. A successfully completed operation returns the 200 response code and a new pair of tokens in the response body.

      

   5. Save the access and refresh token locally for further use. To authorize your access in the Swagger UI, repeat step 2.

4. When you finish working with the Swagger UI:

   1. At the top right corner of the Veeam Plug-in for Nutanix AHV public API page, click Authorize.

   2. In the Available authorizations window, click Logout.

      

After you get authorization, you can send HTTP requests to Veeam Plug-in for Nutanix AHV REST API collections and resources in the Swagger UI.

To send a request:

1. On the Veeam Plug-in for Nutanix AHV public API page, expand a resource to which you want to perform an operation.
2. In the list of request methods, click the required method.
3. In the expanded method window, click Try it out.
4. Enter parameter values if required.
5. Click Execute.

The Swagger UI returns a response body as well as a response code and response headers. Additionally the Swagger UI generates a curl command and a URL for your request.