Table of Contents

Table of Contents

Nutanix API Introduction

When discussing the Nutanix Prism Element and Prism Central APIs, it is important to consider the different versions that are available.  This article will discuss the versions that are available today.  Each available version is described differently, as follows:

Authentication

Authentication against the Nutanix REST APIs is done using HTTP Basic Authentication. Requests on HTTP port 80 are automatically redirected to HTTPS port 443. This requires that a valid cluster or configured directory service credential is passed as part of the API request. To complete any Nutanix API request, a minimum of READ access is required. Appropriate administrative credentials are required for API requests that make entity or cluster changes; POST, PUT and DELETE.

Prism Element versus Prism Central

Prism Element APIs are cluster-specific and are designed to manage and manipulate entities within a specific cluster. Prism Central APIs include a larger set of APIs designed to manipulate entities that aren’t necessarily specific to a single cluster. These include Nutanix products accessed via Prism Central such as Service Service and Nutanix Kubernetes Engine (NKE).

Security

The commands throughout this article show use of the --insecure cURL parameter. This parameter disables SSL certificate verification and allows connection even when a connection cannot be guaranteed secure. Consider the risk and security implications of bypassing certificate verification before using --insecure in a production environment.

cURL

cURL, used for demonstration purposes throughout this guide, provides a simple and cross-platform method of testing API requests. Postman is an alternative for users that prefer a graphical approach and the PowerShell Invoke-WebRequest command for Windows users.

Nutanix REST API Versions

As of January 2023, there are four publicly available Nutanix APIs. Note that while you may see API v0.8 listed in the Nutanix Prism REST API Explorer, it is strongly recommended to use v3 APIs wherever possible, with plans to migrate to the v4 APIs as they become generally available.  The versions available can be dictated by the Nutanix AOS or Prism Central version installed.  For this article, v0.8 is mentioned for completeness reasons only and should not be used in production. The API versions available today are as follows.

  • v1 (Prism Element only)
  • v2.0 (Prism Element only)
  • v3 (Prism Central only)
  • v4 (Early Access via Prism Central only)

Prism Element API v1

Status: Deprecated; should only be used when GA versions are not available. For example, collecting cluster performance statistics can be done using API v1 via Prism Element.

Chronologically, API v1 was released before the v0.8 and was used to manage VMs, storage containers, storage pools and many other cluster-specific entities. Before the release of API v2.0, the v1 and v0.8 APIs were how user scripts interacted with Nutanix clusters. Some of the API endpoints could only be used with the AHV hypervisor and some could be used across multiple hypervisors such as AHV and ESXi.

This URL demonstrates a v1 API request that lists all storage containers within a cluster:

				
					https://[cluster_ip]:9440/api/nutanix/v1/containers
				
			

The same request can be submitted with cURL:

				
					curl -X GET 'https://[cluster_virtual_ip]:9440/api/nutanix/v1/containers' -H 'Accept: application/json' -H 'Content-Type: application/json' --insecure --basic --user [cluster_username]:[cluster_password]
				
			

The most common use case for the Prism Element v1 API is virtual machine performance metrics. All other use case are covered by later API versions.

Prism Element API v2.0

“The Nutanix REST APIs allow you to create scripts that run system administration commands against the Nutanix cluster. The API enables the use of HTTP requests to get information about the cluster as well as make changes to the configuration. Output from the API calls are returned in JSON format. The v2 API is an update of the v1 API. Users of the v1 API are encouraged to migrate to v2.”

Status: Available

The Prism Element v2.0 APIs are the first GA version combining most functionality from the historical v0.8 and v1 APIs. Many of the entities and endpoints available in v0.8 and v1 were published in v2.0, along with back-end improvements and endpoint renaming. The v2.0 APIs are also the first official GA Nutanix API.

The Prism Element v2.0 APIs highlighted a number of differences.

  1. Rename: containers to storagec_containers
  2. Rename: storagePools to storage_pools
  3. Endpoint naming standard from camelCase to snake-case

This URL demonstrates a Prism Element API v2.0 request to list all storage_containers within a cluster.

				
					https://[cluster_virtual_ip]:9440/api/nutanix/v2.0/storage_containers
				
			

The same request can be submitted with cURL:

				
					curl -X GET 'https://[cluster_virtual_ip]:9440/api/nutanix/v2.0/storage_containers' -H 'Accept: application/json' -H 'Content-Type: application/json' --insecure --basic --user [cluster_username]:[cluster_password]
				
			

API v1 and v2.0 Summary

All APIs outlined so far return a JSON response that is easily consumable by many programming or scripting languages. Additionally, all API requests so far have been HTTP GET requests that do not require a JSON payload/POST body.

Prism Central API v3

“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.”

Status: Available

The Prism Central v3 APIs were released as GA on April 17th 2018 are supported on Prism Central Only. End user v3 APIs must not be consumed via Prism Element.

Prism Element API v1 and v2.0 HTTP GET requests list entities and request a specific entity. HTTP POST, PUT and DELETE requests are used to make changes.

The Prism Central v3 APIs operate slightly differently. The Prism Central v3 APIs are built around an Intentful paradigm, described as “move the programming from the user to the machine.” Instead of writing a large amount of code to complete a specific action, the intentful design allows the user to specify the desired state and the system will “figure out” the best way to get there. This is similar to configuration management frameworks like Salt, Puppet, Chef, Ansible and the PowerShell DSC.

This Prism Central v3 API requests a list of virtual machines, along with the following key differences between the same request using previous APIs.

  • The request method is HTTP POST versus HTTP GET in Prism Element v1 and v2.0 APIs
  • A mandatory JSON payload specifies the type of entity being requested
  • A mandatory URL component indicates the request will list the virtual machines
				
					https://[prism_central_virtual_ip]:9440/api/nutanix/v3/vms/list
				
			

This JSON payload is included with the request.

				
					{"kind":"vm"}
				
			

The same request can be submitted with cURL:

				
					curl -X POST 'https://[prism_central_virtual_ip]:9440/api/nutanix/v3/vms/list' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"kind":"vm"}' --insecure --basic --user [prism_central_username]:[prism_central_password]
				
			

cURL Command Analysis

The Prism Central v3 API request demonstrated above can be analysed as follows.

  • curl -X POST – Run cURL and specify that we will be making an HTTP POST request (as opposed to HTTP GET)
  • https://[prism_central_virtual_ip]:9440/api/nutanix/v3/vms/list – Specify the complete request URL
  • -H 'Accept: application/json' – Specify the content types the server is able to understand
  • -H 'Content-Type: application/json' – Tell the server what type of data is being sent
  • -d '{"kind":"vm"}' – The POST request’s JSON payload/body
  • --insecure – Ignore invalid SSL certificates. Use caution before ignoring SSL certificates in a production environment.
  • --basic – Tell the cURL command that we will authenticate using HTTP Basic Authentication
  • --user <cluster_username>:<cluster_password> – Specify the username and password to use during basic authentication

Prism Central API v4

"Our goal with the version 4 REST APIs is to provide a comprehensive and consistent set of APIs for operating the Nutanix Cloud Platform. V4 API has semantics based on open standards and delivers enhanced usability and developer experience."

Status: EA (Early Access) and RC (Release Candidate).  Note: EA and RC status is namespace-dependent.

Released as EA (Early Access) in Prism Central pc.2022.6, the Prism Central v4 APIs are a ground-up rewrite of the Nutanix Prism REST APIs. Some of the highlighted new features are as follows.

  • Language-specific SDKs
  • API namespaces for API separation
  • Strict API versioning
  • Request ID header support for request idempotency
  • If-Match header support for mid-air collision avoidance
  • Redesigned documentation portal
  • Consistent object schemas across all supported entities
  • Consistent URL patterns across all supported entities

This GET request demonstrates an images list request using the Prism Central v4 APIs currently available as EA in Prism Central pc.2022.6.

				
					https://[prism_central_virtual_ip]:9440/api/vmm/v4.0.a1/images
				
			

The same request can be submitted with cURL:

				
					curl -X GET 'https://[prism_central_virtual_ip]:9440/api/vmm/v4.0.a1/images' -H 'Content-Type: application/json' --insecure --basic --user [prism_central_username]:[prism_central_password]
				
			

Important points to note:

  1. The user must specify the namespace that exposes the required API. This example uses the vmm namespace.
  2. The user must specify the API version. This example uses API version v4.0.a1.

For more information, including documentation, guides and code samples, see the Nutanix v4 API Introduction.

Nutanix REST API Use Cases

The following list summarises the different Nutanix API version use cases.

  • v1 (Prism Element)
    • Legacy application support and VM performance metrics
    • Should not be used outside of specific circumstances

  • v2.0 (Prism Element)
    • Merge of v0.8 and v1 APIs into single GA API
    • cluster-specific tasks. For example, storage container management, storage container performance statistics

  • v3 (Prism Central)
    • environment-wide configuration and entity management
    • Prism Central application and product management including Nutanix Self Service, Nutanix Kubernetes Engine, Nutanix Flow

  • v4 (Prism Central)
    • Multi-cluster entity management. This includes cluster images, virtual machines, networking, AIops
    • See Nutanix API v4 Intro for detailed information, including official v4 API documentation

Summary

This article covered the various Nutanix Prism Element and Prism Central API versions, the differences between them and why a specific version would be used. For more information, refer to these additional resources.