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

Nutanix API Intro

When discussing the Nutanix APIs, it is important to consider the different versions that are available.  Let’s take a look at the versions that are available today.  As an intro, here is how Nutanix describes these APIs:

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

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. A Cluster Admin account is not required to complete API requests, unless that request explicitly carries out an action that makes changes to a cluster.

Prism Element “vs” Prism Central


Prism Element APIs are cluster-specific i.e. designed to manage and manipulate entities on the cluster Prism is running on. Prism Central APIs include a larger set of APIs designed to manipulate entities that aren’t necessarily specific to a single cluster.

API Versions

As at January 2019, there are three publicly available Nutanix APIs. Note that while you may see API v0.8 listed in the REST API Explorer in Nutanix Prism, it is strongly recommended to use v3.0 APIs wherever possible.  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.

The API versions available today are as follows.
  • v1
  • v2.0
  • v3

Note re security: In the sample commands below you’ll see use of the –insecure cURL parameter. This is used to get around SSL/TLS verification issues when using self-signed certificates. Please consider the potential pitfalls and security implications of bypassing certificate verification before using –insecure in a production environment.  Windows users can download cURL from the curl website.  The same precautions apply when providing a username and password on the command-line. This should be avoided when possible, since this method shows both the username and password in clear text.

Additional note re cURL: cURL is used in this article to provide a simple and cross-platform way of testing API requests from the command-line. This approach won’t suit everyone and there are many other ways of testing API requests. For example, Postman for those that prefer a more graphical approach, Invoke-WebRequest for Windows users that prefer to use PowerShell or the Python interpreter for others writing cross-platform scripts.

API v1

Status: Available

This set of APIs, chronologically, was released before the v0.8 APIs that aren’t covered here. They were used, for example, to manipulate and view VMs, storage containers and storage pools, plus many other entities. For some time, the v1 and v0.8 APIs were the only way we, as developers, had to programmatically interact with Nutanix clusters. Some of the API endpoints could only be used with the AHV hypervisor and some could be used across multiple hypervisors e.g. AHV and ESXi.
Here’s a simple example of a v1 API request URL to list all storage containers on a cluster:

https://<cluster_virtual_ip>:9440/api/nutanix/v1/containers
Alternatively, this HTTPS API request can be carried out using the curl command:

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>
One of the reasons to use API v1 today is to collect entity performance information. For example, a custom dashboard could contain storage performance. In an upcoming Nutanix Developer blog article will discuss the API v1 performance metrics and how to use them.

API v2.0

Status: Available

The v1 APIs worked really well. In fact, they were (and still are, in some respects) how the Prism UI gathers data from the cluster. Another over-simplification would be to say that the v2 APIs are where the v0.8 and v1 APIs merged. Many of the entities and endpoints available in v0.8 and v1 were made available in v2, along with a huge amount of back-end cleanup, endpoint renaming and generally making the APIs better. The v2 APIs are also the first officially GA API made available by Nutanix.


If you have some exposure to the previous v0.8 and v1 APIs, moving to the v2 APIs will highlight a number of differences. For example “containers” got renamed to “storage_containers” and “storagePools” got renamed to “storage_pools”. The difference? A consistent naming convention in the form of snake-case across all entities.


Here’s a basic example of a v2 API request to list all storage_containers on a cluster:

https://<cluster_virtual_ip>:9440/api/nutanix/v2.0/storage_containers
 
Alternatively, this HTTPS API request can be carried out using the curl command:

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>

Quick Summary

Before moving forward, note that all the APIs above return a JSON response that is easily consumable by many programming or scripting languages. Also, all the requests above are HTTP GET requests and do not require a payload (POST body).

API v3

Status: Available

The v3 APIs, which were released as GA on April 17th 2018, are the first departure from how things were done before.

We used GET requests to get data from a cluster and POST methods to make changes – the v3 APIs are a little different. All the previous APIs still required the developer to tell the system what to do and how to do it. The v3 APIs, on the other hand, are the first APIs built around an Intentful paradigm, that is, move the programming from the user to the machine. Instead of writing a ton of code to get something done, we tell the system what the desired state is and the system will “figure out” the best way to get there. This may sound familiar to those using configuration management frameworks like Salt, Puppet, Chef, Ansible, PowerShell DSC etc.

How this all happens is beyond the scope of this article, but take a look at the request below. It is still getting similar information to the previous requests but with a couple of key differences.
  1. It is an HTTP POST request, not GET.
  2. A JSON payload (POST body) is required so that the cluster knows what type of entity to return. In this example, we’re talking about VMs.
  3. We’re telling the system what we want to do with the data. In this case, we want to list all VMs.
  4. While this request can be run without issue against Prism Element, it can also be run against Prism Central. More on that later.
https://<prism_central_or_cluster_virtual_ip>:9440/api/nutanix/v3/vms/list
And the JSON post body:

{"kind":"vm"}

Alternatively, this HTTPS API request can be carried out using the curl command:

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 <cluster_username>:<cluster_password>

cURL Command Analysis

As an extra step, let’s take the v3 API request above and look at what each part of the command is doing. If you are familiar with using cURL to make API requests, this will look very familiar.
  • 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 URL to send the request to.
  • -H ‘Accept: application/json’ \ – Specify the content types the client is able to understand.
  • -H ‘Content-Type: application/json’ \ – Tell the server what type of data is actually sent.
  • -d ‘{“kind”:”vm”}’ \ – For our POST request, specify the request **body** i.e. the parameters to send along with the request.
  • –insecure \ – Tell the cURL command to ignore SSL certificate verification errors (please see the note above re what this means).
  • –basic – Tell the cURL command that we will authenticate using **Basic Authentication**.
  • –user <cluster_username>:<cluster_password> – Specify the username and password to use during basic authentication.

API version use cases


With what we know about the various API versions now, let’s take a look at why you might use each API.

  • v1: Legacy application support and cluster-wide performance metrics.
  • v2.0: Migration away from legacy APIs, combination of older v0.8 and v1 APIs into single GA API, cluster-specific tasks e.g. storage container information & management.
  • v3 on Prism Element: Latest supported API aimed at managing cluster-specific entities such as VMs.
  • v3 on Prism Central: Latest supported API aimed at managing environment-wide configuration and entities. Unlike API v3 on Prism Element, this includes a vast array of entities such as Nutanix Calm Blueprints, RBAC, Applications, Nutanix Flow Network Security Rules.

Summary

At this point, you know what the available APIs versions are and what some of the differences are between them. For further information, please see the Nutanix Developer API Reference.