Representational state transfer ( REST ) Application Programming Interface (API) 3.0 is based on an intentful API philosophy. According to the intentful API philosophy the machine should handle the programming instead of the user enabling the datacenter administrator able to focus on the other tasks. You need to specify the end state of an entity and the system will compile and execute a series of steps to achieve the defined end state of the entity. The progress to achieve the desired state is tracked through waits and events. This approach is similar to the Google Kubernetes standard.

All the entities and the list of entities follow a homogenous specification format resulting in ease of programming despite different entities being involved. Also, this enables the user to get familiar with the APIs quickly.

Intentful APIs reduces the number of action verbs required to achieve the desired state of an entity. Most of the changes can be achieved by defining the desired state of an entity rather than through a series of action verbs.

All API users should have valid Prism login credentials to send API calls to the Prism server. APIs on nutanix.dev portal are publicly available to all valid users without special permissions for viewing purposes.

This document covers APIs that are available in pc2022.11 release.

• The metadata section has fields that relate to all kinds of entities and can be updated instantly by the system.
• The spec section cannot be updated after initialization by the system without a user or automation intervention.
• The status section has a copy of the currently enforced version of the spec section and other fields that are managed or updated automatically by the system. Few fields in the status section can be updated by the user as well.
• The parent_reference field is mandatory for snapshot and backup entities and is present in the normal entities, if the entities are created with the parent_reference field populated (clone or restore).
• Any field that represents a defined type has the type name as a suffix. For example, backup_factory and vm_reference.

This section describes some of the issues identified in V3 APIs that you might encounter.

• ENG-321951- While attempting to get a list of all VMs on Prism Central, we have observed that only AHV VMs are returned, but ESXi VM list is not retrieved.

• ENG-453487- Users with insufficient permissions receive an HTTP 200 response instead of an HTTP 403 response for view alert API requests. These users can be like "Developer", "Operator", or custom roles that do not have sufficient permission to view alerts. This is a generic issue for all V3 API requests with insufficient permissions.

Nutanix API versions – What are they and what does each one do?

What to expect post pc.2022.1 release?

A REST API request and response can be classified into the following components.

The request URI consists of {URI-scheme} :// {URI-host} / {/} ? {query-string}.

HTTP defines methods to indicate the desired action to be performed on the identified resource.

HTTP request headers provide meta-information about a request. The request body contains the data that client wants to send to the server. For example, Content-Type and Content-Transfer-Encoding.

HTTP response headers provide meta-information about a response. The response consists of status code (three-digit number), content type, and body of the response.

An entity structure comprises of the following components.

• Metadata - Metadata provides high-level information about the related entity including entity uuid, kind, and spec_version.
• Status - Status provides information about the current state of the related entity including entity name, state, and entity-specific status information.
• Specification - For a GET request, the specification section of the JSON response displays similar information as status section. However, for of POST request, the specification section provide details of what should be the desired state of the entity. For example, you can use the following JSON payload to create a basic VM. The payload denotes the minimum parameters required to create a VM by using the V3 APIs. All the missing specification items like CPU and RAM are configured with default values.

{
"spec":{
"name":"NewVM",
"resources":{
}
},
"metadata":{
"kind":"vm"
}
}

All requests to the Nutanix REST APIs must be authenticated. The following authentication types are supported.

• Basic Authentication: The user provides username and password every time a request is sent as the authentication header.
• Session Authentication: The user credentials are stored in a cookie.

The following are the code snippets to authenticate a user.

Python

#!/usr/bin/env python3.7
import urllib3
import requests
from base64 import b64encode
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
request_url = 'https://10.0.0.1:9440/api/nutanix/v3/vms/list'
username = 'admin'
password = 'password'
encoded_credentials = b64encode(bytes(f'{username}:{password}',
encoding='ascii')).decode('ascii')
auth_header = f'Basic {encoded_credentials}'
payload = '{"kind":"vm"}'
headers = {'Accept': 'application/json', 'Content-Type': 'application/json',
'Authorization': f'{auth_header}', 'cache-control': 'no-cache'}
response = requests.request('post', request_url, data=payload, headers=headers,
verify=False)
print(response.status_code)

C#

using System;
using System.Net;
using System.Text;
namespace ConsoleApp1
{
class Program
{
static void Main(string[] args)
{
string ClusterUsername = "admin";
string ClusterPassword = "Ntnx2017!";
string RequestUrl = "https://192.168.1.131:9440/api/nutanix/v3/vms/list";
string Payload = "{\"kind\":\"vm\"}";
string AuthHeader = System.Convert.ToBase64String(
System.Text.ASCIIEncoding.ASCII.GetBytes(
ClusterUsername + ":" + ClusterPassword));
ServicePointManager.ServerCertificateValidationCallback = (
(sender, certificate, chain, sslPolicyErrors) => true);
ServicePointManager.Expect100Continue = true;
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
String authHeader = System.Convert.ToBase64String(
System.Text.ASCIIEncoding.ASCII.GetBytes(
ClusterUsername + ":" + ClusterPassword));
var request = (HttpWebRequest)WebRequest.Create(RequestUrl);
var requestBody = Encoding.ASCII.GetBytes(Payload);
HttpWebResponse HttpResponse = null;
request.Headers.Add("Authorization", "Basic " + AuthHeader);
request.Headers.Add("Accept-Encoding", "application/json");
request.ContentType = "application/json";
request.Accept = "application/json";
request.Method = "POST";
var newStream = request.GetRequestStream();
newStream.Write(requestBody, 0, requestBody.Length);
newStream.Close();
HttpResponse = (HttpWebResponse)request.GetResponse();
Console.WriteLine(HttpResponse.StatusCode);
Console.ReadKey();
}
}
}

PowerShell

# set the basic properties for the request
$RequestUri = "https://10.0.0.1:9440/api/nutanix/v3/vms/list"
$Payload = "{""kind"":""vm""}"
$Username = "admin"
$Password = "password"
# create the HTTP Basic Authorization header
$pair = $Username + ":" + $Password
$bytes = [System.Text.Encoding]::ASCII.GetBytes($pair)
$base64 = [System.Convert]::ToBase64String($bytes)
$basicAuthValue = "Basic $base64"
# setup the request headers
$Headers = @{
'Accept' = 'application/json'
'Authorization' = $basicAuthValue
'Content-Type' = 'application/json'
}
# disable SSL certification verification
# you probably shouldn't do this in production ...
if (-not (
[System.Management.Automation.PSTypeName] `
'ServerCertificateValidationCallback').Type)
{$certCallback = @"
using System;
using System.Net;
using System.Net.Security;
using System.Security.Cryptography.X509Certificates;
public class ServerCertificateValidationCallback
{
public static void Ignore()
{
if(ServicePointManager.ServerCertificateValidationCallback ==null)
{
ServicePointManager.ServerCertificateValidationCallback +=
delegate
(
Object obj,
X509Certificate certificate,
X509Chain chain,
SslPolicyErrors errors
)
{
return true;
};
}
}
}
"@
Add-Type $certCallback
}
[ServerCertificateValidationCallback]::Ignore()
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
# submit the request
Invoke-WebRequest `
-Uri $RequestUri `
-Headers $Headers `
-Method "POST" `
-Body $Payload `
-TimeoutSec 5 `
-UseBasicParsing `
-DisableKeepAlive `
| ConvertFrom-Json | Select *

PHP

<?php
$username = 'admin';
$password = 'password';
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => 1,
CURLINFO_HEADER_OUT => TRUE,
CURLOPT_URL => 'https://10.0.0.1:9440/api/nutanix/v3/vms/list',
CURLOPT_USERPWD => $username . ':' . $password, CURLOPT_POST => 1, CURLOPT_SSL_VERIFYHOST => FALSE, CURLOPT_SSL_VERIFYPEER => FALSE,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Accept-Encoding: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'kind' => 'vm'
])
]);
$result = curl_exec($ch);
curl_close($ch);
if(!$result) {
die('Error: "' . curl_error($ch) . '". Code: ' . curl_errno($ch));
}
else {
echo($result);
}

From Prism Central release 2022.1 onwards, the v3 intentful API is enhanced to protect data consistency, especially in concurrent race conditions. As a result of this enhancement, response time for the synchronous API requests is improved and there are some behavior changes from an API consumption perspective.

1. In the current v3 API workflow, clients will get a synchronous API response that contains task and entity UUID. Post which clients should send GET API on the task periodically until the task succeeds or fails. Clients can also send GET API on the entity.

   • Behavioral changes: Some of the synchronous errors will be reported asynchronously now.

   1. Invalid idempotency UUID error:

      Current API behavior: If POST API contains invalid idempotency UUID, clients will receive a synchronous bad request error with an HTTP code 400.

      Expected change: If POST API contains invalid idempotency UUID, clients will get a synchronous API response with an HTTP code 202(accepted). GET API on the task will return a bad request error.

   2. Authorization errors:

      Current API behavior: Clients will get synchronous authorization errors (for example- HTTP code 403 forbidden error).

      Expected change: Clients will get a synchronous API response with an HTTP code 202 (accepted). GET API on the task will show an authorization error.

   3. Incorrect category mapping error:

      Current API behavior: If an intentful API payload has a project reference and uses categories mapping but the category for the project does not exist, the client will get an error response with an HTTP code 404(not found).

      Expected change: If an intentful API payload has a project reference and uses categories mapping but the category for the project does not exist, the client will receive a synchronous API response with an HTTP code 202 (accepted). GET API on the task will show a “not found” error.

   4. Invalid user detail error:

      Current API behavior: If an intentful API payload has user_uuid or username in owner_reference but the corresponding user does not exist, the client will receive an API response with an HTTP code 404.

      Expected change: If an intentful API payload has user_uuid or username in owner_reference but the corresponding user does not exist, clients will get a synchronous API response with an HTTP code 202(accepted). GET API on the task will show a bad request error.

   5. . Missing user detail error:

      Current API behavior: If an intentful API payload does not have user_uuid or username in owner_reference and the login user does not exist, the client will get an API response with an HTTP code 404.

      Expected change: If an intentful API payload does not have user_uuid or username in owner_reference and login user does not exist, clients will get a synchronous API response with an HTTP code 202(accepted). GET API on the task will show a bad request error.

   • Format changes for some of the synchronous API responses:

     Current API behavior: Response to an intentful POST, PUT, or DELETE API will contain tenant_uuid, owner_uuid, owner_username, service_name, session_log_uuid, trace, user_uuid, username, remote_authorization, session_json_dict, incap_req_id, project_reference or category information.

     Expected change: Main processing will occur after a synchronous response to the client. As a result, synchronous response to an intentful POST, PUT, or DELETE API will not contain tenant_uuid, owner_uuid, owner_username, service_name, session_log_uuid, trace, user_uuid, username, remote_authorization, session_json_dict, incap_req_id, project_reference or category information.

     If API consumers are expecting these properties in the synchronous response before, they have to submit a GET/LIST request to inspect these properties.

2. The version control workflow for v3 intentful PUT and DELETE APIs:

• Absolutely no version control check for DELETE APIs:

  Current API behavior: DELETE API will fail if an incorrect spec_version is provided as one of the request arguments.

  Expected change: DELETE API will always delete the entity. No version control is applicable on the DELETE request.

• Edit conflict error could be reported asynchronously:

  Current API behavior: If v3 PUT APIs are conflicting with v2 PUT APIs on the same entities, the client will receive an HTTP code 409 response for v3 PUT APIs.

  Expected change: If v3 PUT APIs are conflicting with v2 PUT APIs on the same entities, the client will receive an HTTP code 202 response for v3 PUT APIs and will receive the task failed response with an edit conflict error asynchronously.

• More restrictive version control by using spec_hash:

  Current API behavior: GET/LIST API will return a response that may contain one of the values for version control, it could be spec_version or spec_hash. spec_version is numeric while spec_hash is a string.

  Whichever value is provided in the GET/LIST API, the same value should be included in the next PUT API payload of the same entity.

  Expected change: GET/LIST API will provide both spec_hash and spec_version in API response. Use of spec_hash is not enforced but could be enforced in future releases.

• The version control value in the GET API response will not change when a PUT request is in progress:

  Current API behavior: If there are one GET request and one PUT request on the same entity, the version control value from the GET request response might be different depending on the current state of the entity. The behavior is not deterministic.

  Expected change: If there is one GET request and one PUT request on the same entity, the spec_hash value of the GET request response will always be the same as it was before the PUT request until the PUT is completed.

1. V3 intentful POST API and the following GET API:

• Get API request for new entity:

  Current API behavior: If a POST API fails asynchronously, the following GET API on the same entity will get an HTTP code 202 response with the entity in an error state.

  However, GET API on the same entity after 5+ minutes will show an HTTP code 404 response reporting the entity does not exist.

  Expected change: If a POST API fails asynchronously, GET API on the same entity will always show an HTTP code 404 response meaning the entity does not exist.

• The intent spec is an entity we created to record previous and ongoing requests from v3 POST/PUT/DELETE APIs. There should be only one intent spec for each entity if the intent spec exists:

  Current API behavior: If the client queries intent spec for an entity immediately after getting an HTTP code 202 response for the v3 POST API on this entity, the intent spec will always be present.

  Expected change: If the client queries intent spec for an entity immediately after getting an HTTP code 202 response for the v3 POST API on this entity, the intent spec may not be created yet.

4. Prism Central upgrade to pc.2022.1 and following releases:

   Current API behavior: The pending and running API requests will continue to execute after an upgrade.

   Expected change: During the pc.2022.1 version upgrade, all pending and running API requests and related tasks will be marked as failed after a restart. This will be shown even though they may be in progress and completed in the middle of the upgrade period. This behavior only applies to upgrades from releases before pc.2022.1 to releases equal to or after pc.2022.1. All future upgrades from pc.2022.1 release will remain the same as before where pending and running API requests will continue to execute after an upgrade.

5. Multiple nodes upgrade:

• pc.2022.1 version can take care of the scenarios where Prism Central has the new version and Prism Element is still at the older version.

• Any task (for existing create, update, delete v3 API operations) that is in running state during the upgrade will be marked failed. This also applies to new requests that come before the upgrade ends. The recommendation is to wait until the upgrade finishes before executing any v3 create, update, delete API.

6. Schema consistency:

   • API schema in Prism Central will be used in case there is a discrepancy between Prism Element and Prism Central. There will be a change of behavior when Prism Central has a post pc.2022.1 version.

     Current API behavior: API responses for POST, PUT, and DELETE API on Prism Central will match API schema on Prism Element.

      **Expected change**: API response for POST, PUT, and DELETE API on Prism Central will match API schema on Prism Central.
     

Perform the following procedure to generate the code snippet for creating a VM based on the input parameters.

1. Under VMs, click POST VMs and navigate to the end of the page.

2. In the Code Generation panel, under the Settings tab, enter the value of the following parameters.

   1. Enter the username of the Prism Central in the Username field.
   2. Enter the password in the Password field.
   3. Enter the IP address of the Prism Central in the Host field.

3. Under the Body tab, enter the value of all the required parameters as described in the Request Body section. Optionally, you can also enter the values of the optional parameters.

   1. Under Specification, enter the description of VM in a string format against the description attribute. The maximum length allowed is 1000 characters only.
   2. Under Resources do the following.
      1. Enter the value of number of logical threads per core in an integer format against the num_threads_per_core attribute. The minimum value allowed is 1.
      2. Enter the value of current or desired power state of the VM in a string format against the power_state attribute.
      3. Enter the value of number of vCPUs per socket in an integer format against the num_vcpus_per_socket attribute. The minimun value allowed is 1.
      4. Enter the value of number of vCPU sockets in an integer format against the num_sockets attribute. The minimum value allowed is 1.
   3. Under Name, enter the name of the VM in a string format. The maximum length allowed is 64 characters only.
   4. Under Metadata do the following.
      1. The last_update_time is a read-only attribute indicating UTC date and time in an RFC-339 format, when the VM was last updated in a string format.
      2. The kind is a read-only attribute indicating the kind name in a string format. The default value is VM.
      3. Enter the value of VM uuid in a string format against the uuid attribute. The valid pattern is ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fAF0-9]{12}$.

4. Under the Code Generation tab, select the scripting languages to view the code snippet of creating a VM.

   You can either select Python or PowerShell or Shell or Go or Java or JavaScript or Node or Obj-C or PHP or Ruby or Swift or C# or C.

   The code snippet appears in the selected scripting language. You can use the code snippet to create a VM in your environment.

Perform the following procedure to generate the code snippet for updating an existing VM based on the input parameters.

1. Under VMs, click PUT VMs and navigate to the end of the page.

2. In the Code Generation panel, under the Settings tab, enter the value of the following parameters.

   1. Enter the UUID of the VM that needs to be updated in the UUID field.
   2. Enter the username of the Prism Central in the Username field.
   3. Enter the password in the Password field.
   4. Enter the IP address of the Prism Central in the Host field.

3. Under the Body tab, enter the value of all the required parameters as described in the Request Body section. Optionally, you can also enter the values of the optional parameters.

   1. Under Specification, enter the description of VM in a string format against the description attribute. The maximum length allowed is 1000 characters only.
   2. Under Resources do the following.
      1. Enter the value of number of logical threads per core in an integer format against the num_threads_per_core attribute. The minimum value allowed is 1.
      2. Enter the value of current or desired power state of the VM in a string format against the power_state attribute.
      3. Enter the value of number of vCPUs per socket in an integer format against the num_vcpus_per_socket attribute. The minimun value allowed is 1.
      4. Enter the value of number of vCPU sockets in an integer format against the num_sockets attribute. The minimum value allowed is 1.
   3. Under Name, enter the name of the VM in a string format. The maximum length allowed is 64 characters only.
   4. Under Metadata do the following.
      1. The last_update_time is a read-only attribute indicating UTC date and time in an RFC-339 format, when the VM was last updated in a string format.
      2. The kind is a read-only attribute indicating the kind name in a string format. The default value is VM.
      3. Enter the value of VM uuid in a string format against the uuid attribute. The valid pattern is ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fAF0-9]{12}$.

4. Under the Code Generation tab, select the scripting languages to view the code snippet of creating a VM.

   You can either select Python or PowerShell or Shell or Go or Java or JavaScript or Node or Obj-C or PHP or Ruby or Swift or C# or C.

   The code snippet appears in the selected scripting language. You can use the code snippet to update a VM in your environment.