Nutanix v4 API Migration Guide

Table of Contents

Introduction

Nutanix APIs have grown over the past decade and over a number of major releases to support multiple endpoints, clusters, products, and operations. The version 4 (or v4) REST APIs have been designed for consistency across all products, consolidation into a single platform API, and an “API first” mentality where API documentation and supporting SDKs are published concurrently with each product update.

Related Documentation

The first set of Nutanix v4 API and SDK documentation is now live and can be accessed below.  If you are an existing user of our v2.0 or v3 APIs you may wish to start with the v4 API Migration Guide.

Note: The code sample library will be expanded as new APIs are released.

The following table shows the available Nutanix v4 API Namespaces, the current version status (Early Access or Release Candidate) and the corresponding Prism Central + AOS version requirements.

API NamespaceNamespace EndpointStatusPrism Central versionAOS version
AI OpsaiopsEApc.2022.6 or later6.5
Cluster ManagementclustermgmtRCpc.2023.3 or later6.7
FilesfilesEApc.2022.6 or later6.5
Identity and Access Management (IAM)iamRCpc.2023.3 or later6.7
Lifecycle Management (LCM)lcmEApc.2022.6 or later6.5
NetworkingnetworkingRCpc.2023.3 or later6.7
PrismprismEApc.2022.6 or later6.5
Virtual Machine ManagementvmmEApc.2022.9 or later6.6
StoragestorageEApc.2022.6 or later6.5
Data ProtectiondataprotectionEApc.2023.3 or later6.7
Flow ManagementmicrosegEApc.2023.3 or later6.7
Prism Central pc.2023.3 and AOS 6.7, released August 29th 2023, introduces support for ESXi VM as part of the Virtual Machine Management namespace, and Flow Management, available through the microseg namespace.

These APIs represent the next step for cloud consumption, integration and automation of the Nutanix Cloud Platform.  Subsequent releases will expose additional v4 APIs which will provide a single platform for all old and legacy Prism APIs.  All older and legacy APIs will be gradually deprecated before being decommissioned.  End of support for legacy APIs will be announced as more information becomes available.

For some time, Nutanix API consumers have become accustomed to using various product-specific and Prism API endpoints, usually dependent on the action required. The table below shows a high-level description of the Prism API endpoint collections available today.

API/Version/Name Published By Status
v1
Prism Element Only
Available but deprecated; should not be used directly unless a v1-only action is required (e.g. virtual machine performance metrics)
v2.0
Prism Element Only
GA; Generally available for all Prism Element users. The current API endpoints are applicable to cluster-local operations. Includes but is not limited to virtual machines, images and storage containers
v3
Prism Central Only
GA; Generally available for all Prism Central users. These API endpoints are for multi-cluster operations. Includes but is not limited to virtual machines and images across multiple clusters, Nutanix Self Service Blueprints and applications and Flow Security Policies

In nearly all cases, the recommendation has been to consume v3 API endpoints via Prism Central and fall back to v1 and v2.0 endpoints only when required.

Nutanix API Documentation

As with all existing Nutanix API reference information covering Prism Element v2.0 and Prism Central API v3, the Nutanix Developer Portal provides the entry point into official documentation for the new Nutanix v4 APIs.

The table below shows where existing and new documentation is published.

Technology/API Version URL
Prism Element v2.0
Prism Central v3
Prism Central v4 API and SDK
Other Nutanix products e.g. Self Service, Databases, Flow Security Central, Container Engine

Existing API Endpoint Examples

The table below shows some of the endpoints available across the various Nutanix Prism Element and Prism Central APIs, with usage examples.

Important note: Take care to note where each request should be sent.  For example, v1 and v2.0 APIs may only be sent to Prism Element IP addresses or FQDNs (Prism Element).  v3 APIs may only be sent to Prism Central IP addresses or FQDNs (Prism Central).  All requests are sent over HTTPS port 9440.

Prism Element v1 - Storage Containers

Endpoint Entity Type/Name Use Case PE/PC? Request Method Request Path
v1/containers
Storage Container
CRUD operations for cluster-local storage containers. Example shows shows listing all storage containers visible on a specific PE instance
PE
GET
/PrismGateway/services/rest/v1/containers

Prism Element v2.0 - Physical Hosts

Endpoint Entity Type/Name Use Case PE/PC? Request Method Request Path
v2.0/hosts
Physical Hosts
Management operations for cluster hosts/nodes. Example shows listing all hosts visible on a specific PE instance.
PE
GET
/api/nutanix/v2.0/hosts

Prism Element v2.0 - Storage Containers

Endpoint Entity Type/Name Use Case PE/PC? Request Method Request Path
v2.0/storage_containers
Storage Container
CRUD operations for cluster-local storage containers. Example shows listing all storage containers visible on a specific PE instance
PE
GET
/api/nutanix/v2.0/storage_containers

Prism Central v3 - Virtual Machines

Endpoint Entity Type/Name Use Case PE/PC? Request Method JSON Payload Request Path
v3/vms
Virtual Machine
CRUD operations for virtual machines. Example shows listing all VMs visible on a specific PC instance. Note the example payload will return a list of the first 20 VMs only
PC
POST
{"kind": "vm"}
/api/nutanix/v3/vms/list

Prism Central v3 - Self Service Blueprints

Endpoint Entity Type/Name Use Case PE/PC? Request Method Request URL
v3/blueprints
Service Service Blueprint
CRUD operations for Self Service Blueprints. Self Service Blueprints are the basis for application lifecycle management, including virtual machine and image configurations specific to an application. Example shows getting details of a specific Self Service blueprint.
PC
GET
/api/nutanix/v3/blueprints/{{uuid}}

Prism Central v3 - Flow Security Policies

Endpoint Entity Type/Name Use Case PE/PC? Request Method Request URL
v3/network_security_rules
Flow Network Security Rule
CRUD operations for Flow Network Security Rules. Flow network security rules form the basis of network traffic flow control between virtual machines, typically managed via Prism Central categories.
PC
DELETE
/api/nutanix/v3/network_security_rules/{{uuid}}

Note: For current Nutanix Prism Central v3 API documentation, see https://www.nutanix.dev/api_references/prism-central-v3/.

Migration to new v4 APIs

The new v4 APIs provide multiple advantages over legacy APIs.  For example:

  • More detailed and improved documentation
  • Elaborated error messages and responses
  • Multi-language SDKs and accompanying code samples
  • Operation-based API grouping into related namespaces and versions

Unlike Prism Central v3 APIs which were grouped under the global “Prism API” name, v4 Nutanix APIs will be grouped by namespace.  See Appendix A (“Available Namespaces”) for a complete list of all current namespaces.

v4 APIs - Multi Language SDKs

The Nutanix v4 APIs introduce an extensive set of SDKs.  The new SDKs are the official and recommended method of consuming the new v4 APIs.  It is strongly recommended that all users migrate to the new v4 API SDKs.

At this stage, the following language SDKs are available:

  • Python
  • Java
  • Go
  • Javascript

Getting Started

Note: Code samples are for demonstration use only and do not follow any particular code standards.  All samples should be tested and modified before being used on live systems.

For demonstration purposes, the Python 3 SDK will be used below.

  • Create and activate a Python virtual environment.  This example uses the Python 3 “venv” but you may use any virtual environment at your discretion (e.g. virtualenv).
				
					# create virtual environment - Linux and Mac OS X
python -m venv ntnxv4
# activate virtual environment
. ntnxv4/bin/activate
				
			
				
					# create virtual environment - Windows
python -m venv ntnxv4
# activate virtual environment
ntnxv4\Scripts\activate.bat
				
			
  • Install the Nutanix SDK.  The SDK you choose will vary based on your requirements; this example shows the installation and usage of the Nutanix Virtual Machine Management (vmm) SDK client.
				
					# install Nutanix vmm SDK client - Linux and Mac OS Linux
pip install ntnx_vmm_py_client
				
			
				
					# install Nutanix client - Windows
pip.exe install ntnx_vmm_py_client
				
			

Refer to the Nutanix SDK documentation for usage details, or refer to the code samples below.

The following code sample demonstrates using the Nutanix Python 3 SDK to generate a count of AHV images.

The following slightly more detailed code sample demonstrates creating an AHV image using the Nutanix Python 3 VMM SDK.

				
					#!/usr/bin/env python

import requests
import time
import ntnx_vmm_py_client
from ntnx_vmm_py_client import ApiClient
from ntnx_vmm_py_client import Configuration

# suppress warnings about insecure connections
# consider the implications of this before production use
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

# setup the API client configuration
config = Configuration()
config.host = "prism_central_ip_here"
# optional; port defaults to 9440
config.port = 9440
config.username = "prism_central_username_here"
config.password = "prism_central_password_here"
# optional; max_retry_attempts defaults to 3
config.max_retry_attempts = 1
# optiona; backoff_factor defaults to 3
config.backoff_factor = 3
config.verify_ssl = False

api_client = ApiClient(configuration=config)
api_instance = ntnx_vmm_py_client.api.ImagesApi(api_client=api_client)

# new image name
image_name = f"centos7minimal_{time.time()}"

# cluster this image will reside on
cluster_extid = "cluster_extid_here"

new_image = ntnx_vmm_py_client.Image()
new_image.name = image_name
new_image.description = "New image created using v4 Python SDK"
new_image.type = ntnx_vmm_py_client.ImageType.DISK_IMAGE
new_image.source = ntnx_vmm_py_client.UrlSource()
new_image.source.allow_insecure = False
new_image.source.url = "https://cloud.centos.org/centos/7/images/CentOS-7-x86_64-GenericCloud-1905.qcow2"
new_image.initial_cluster_locations = [{"extId": cluster_extid}]

# create the image
api_response = api_instance.create_image(new_image)

# return the link that can be examined for errors
print(api_response.metadata.links[0].href)c
				
			
				
					#!/usr/bin/env python

import urllib3
import ntnx_vmm_py_client
from ntnx_vmm_py_client import ApiClient
from ntnx_vmm_py_client import Configuration

# suppress warnings about SSL connections
# consider the implications of this before production use
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

# setup the API client configuration
config = Configuration()
config.host = "prism_central_ip_here"
# optional; port defaults to 9440
config.port = 9440
config.username = prism_central_username_here"
config.password = prism_central_password_here"
# optional; max_retry_attempts defaults to 3
config.max_retry_attempts = 1
# optiona; backoff_factor defaults to 3
config.backoff_factor = 3
config.verify_ssl = False

api_client = ApiClient(configuration=config)
api_instance = ntnx_vmm_py_client.api.ImagesApi(api_client=api_client)

# send the request
api_response = api_instance.get_images_list()

# print a count of images found in this prism central instance
print(f"{api_response.metadata.total_available_results} images found.")
				
			

v4 APIs - Custom API Clients

Although the Nutanix v4 API SDKs are the official and recommended method, custom API clients via REST API requests are still supported.

For the table below, note that all examples are secure connections to a Prism Central instance on HTTPS port 9440.  For example, “https://{{prism_central_ip}}:9440”

Use Case Request Method Request Path JSON Payload Example
List Nutanix clusters
GET
/api/clustermgmt/v4.0.a1/config/clusters
N/A
List Nutanix Images
GET
/api/vmm/v4.0.a1/images
N/A
Get Nutanix Image Details
GET
/api/vmm/v4.0.a1/images/{{uuid}}
N/A
Create Nutanix Image
POST
/api/vmm/v4.0.a1/images
{ "name": "centos7minimal", "description": "CentOS 7 x86_64 Minimal", "type": "DISK_IMAGE", "source": { "url": "", "allowInsecure": false, "$objectType": "vmm.v4.images.UrlSource" }, "initialClusterLocations": [ { "extId": "" } ] }

API v4 - Detailed Usage Example

For this detailed example, we’ll use the new “images” API that is part of the “vmm” VM Management namespace.

URL Request Method
https://{{pc_ip}}:9440/api/vmm/v4.0.a1/images
GET

Key differences between v3 and v4 API responses are as follows.

Prism Central v3 began with a response body containing the JSON shown below:

				
					{
  "api_version": "3.1",
  "metadata": {
    "total_matches": 1,
    "kind": "image",
    "length": 1,
    "offset": 
  },
  "entities": [
   ...
  ]
}
				
			

Key points:

  • Total number of images visible to the Prism Central instance is showing as 1, accessed via the metadata.total_matches property or by parsing the length of the entities list object.

Requesting the same image list using the new v4 APIs would return a response similar to the example shown below:

				
					{
  "$dataItemDiscriminator": "List",
  "data": [
    {
      "sizeBytes": 0,
      "$reserved": {
        "$fqObjectType": "vmm.v4.r0.a1.images.Image"
      },
      "$objectType": "vmm.v4.images.Image",
      "extId": "ed66f8ba-2f96-4108-9270-549c8cb8c851",
      "name": "v4-api-image",
      "description": "Image created with the v4 APIs",
      "type": "ISO_IMAGE",
      "initialClusterLocations": [
        {
          "extId": "0005d771-62c9-3b6a-4b8e-ac1f6b3f91cd",
          "$reserved": {
            "$fqObjectType": "vmm.v4.r0.a1.images.ClusterReference"
          },
        "$objectType": "vmm.v4.images.ClusterReference"
        }
      ]
    }
  ],
  ...
}
				
			

Key points:

  • Total number of images visible to the Prism Central instance is accessed by via the metadata.totalAvailableResults property or by parsing the length of the data list object.  In this example, the data list contains a single object, indicating this Prism Central instance can “see” 1 Prism Central image.  For the purposes of this example, this is an empty/shell image and would need to be modified before being used.

Part 2 - Create Image from URL

URL Request Method JSON Payload
https://{{pc_ip}}:9440/api/vmm/v4.0.a1/images
POST
See snippet below
				
					{
  "name": "centos7minimal",
  "description": "CentOS 7 x86_64 Minimal from v4 APIs",
  "type": "DISK_IMAGE",
  "source": {
    "url": "qcow2_image_url_here",
    "allowInsecure": false,
    "$objectType": "vmm.v4.images.UrlSource"
  },
  "initialClusterLocations": [
    {
      "extId": "cluster_extId_here"
    }
  ]
}
				
			

API v4 - Parsing Responses

The Nutanix Prism Central v3 APIs returned JSON responses that contained relevant information, depending on the type of request sent by the user.  For example, a request to create a Prism Central image from a URL (similar to the request above), would return a JSON response that contained the status and the UUID for the request’s task, if an associated task was created as part of the request.  Below is an example of the relevant part of the v3 API response:

				
					…
  "status": {
  "state": "PENDING",
  "execution_context": {
    "task_uuid": "a28e36af-6776-406a-bc24-f2b1fb6107df"
  }
…

				
			

The task UUID, which can be queried later, is “a28e36af-6776-406a-bc24-f2b1fb6107df”.

It is necessary to understand that the same type of request submitted using the Nutanix v4 APIs will receive a different response.

Besides containing a large amount of additional information, the response object containing details about the related task will look similar to the example shown below:

				
					{
  …
  "metadata": {
    …
    "links": [ {
      "href": "https://<pc_ip>:9440/api/prism/v4.0.a1/config/tasks/ZXJnb24=:68fc2ad3-d7b7-480c-bec1-962e6a446ebc",
      "rel": "self",
      "$reserved": {
        "$fqObjectType": "common.v1.r0.a3.response.ApiLink"
      },
      "$objectType": "common.v1.response.ApiLink"
    } ],
  …
}
				
			

Take note of the “links” object containing the “href” property.  This property specifies the complete URL that would be used to query task-related information for the create image request.  Important note: The complete task extId above is prefixed with ZXJnb24=: and must be left intact when querying task information.

Using the v4 “tasks” API, released as Early Access in Prism Central 2022.1, the following relevant response will be returned from a GET task request:

				
					{
  "$dataItemDiscriminator": "prism.v4.config.Task",
  "data": {
    "extId": "ZXJnb24=:68fc2ad3-d7b7-480c-bec1-962e6a446ebc",
    "operation": "kForwardImageRpc",
    "operationDescription": "Image create",
    "createdTime": "2022-02-28T00:30:34.933023Z",
    "startedTime": "2022-02-28T00:30:34.961362Z",
    "completedTime": "2022-02-28T00:31:11.866702Z",
    "status": "SUCCEEDED",
    "progressPercentage": 100,
    "isCancelable": true,
    …
}

				
			

Using this response, it is easy to see when the task started and finished as well as the task status (completed successfully).  For a task that has not yet been completed, the percentage completed is also available, should a script or app need to monitor the progress of a task.

API REFERENCE FEEDBACK