Nutanix REST API with Golang/Go Tutorial – Part 1 – Nutanix REST API Overview

full course
  1. Nutanix REST API with Golang/Go Tutorial – Part 1 – Nutanix REST API Overview
  2. Nutanix REST API with Golang/Go Tutorial – Part 2 – Authentication
  3. Nutanix REST API with Golang/Go Tutorial – Part 3 – Retrieve information about a VM (IP address, vCPU, MEM)

This blog series is dedicated to the Nutanix REST API and how to automate tasks based on the language Go leveraging the REST API.

The official documentation can be found here: http://developer.nutanix.com/ but this tutorial was started before this has been announced and will focus on the whole process of development with GO and Nutanix REST API.

I will cover the typical tasks you would like to automate. Some examples:

  • Retrieve data like VM and their configs, extract performance values, …
  • Create VM, VLAN, vdisk, projects….
  • Show typical tasks in the new self service portal (SSP)
  • Using different kind of Nutanix REST APIs (v0.8, v1, v2 , v3)
  • … a lot more

Part 1 – Nutanix REST API Overview

This part will show the basic REST API entry points and how to use them directly.

Starting with AOS 5.0 there have been some changes!

There are 4 different API entry points:

Deprecated but still usable with AOS = 5.0

  • https://:9440/api/nutanix/v0.8/                    = v0.8 API so called MGMT API
  • https://CLUSTER-IP_or_CVM_IP:9440/PrismGateway/services/rest/v1/       = all other in < 5.0

Introduced with AOS >= 5.0 -> The v2.0 should union v0.8 and v1

  • https://CLUSTER-IP_or_CVM_IP:9440/api/nutanix/v2.0

Introduced with AOS >= 5.0 but not GA yet

  • https://CLUSTER-IP_or_CVM_IP:9440/api/nutanix/v3.0

The REST API Explorer

The first step is to learn a little bit more about the Nutanix REST API.

So there is a REST API Explorer which shows/documents the versions (v2 and v1) of the Nutanix REST API.

Hint: You may need to login to PRISM before you are able to browse/use the REST API Explorer!

The documentation entry points are:

https://CLUSTER-IP_or_CVM_IP:9440/console/nutanixapi/                        -> v0.8

nutanixapi

https://192.168.178.70:9440/api/nutanix/v2/api_explorer/index.html         -> v2.0

https://192.168.178.70:9440/console/api/index.html                                     -> v1.0

The PRISM GUI is using the REST API. This means everything you can do in PRISM can be done via the REST API and even more. I believe it makes no sense to explain every method of the REST API right now. Instead I will show some basic examples in this tutorial and explain it via implementing use cases. But feel free to browse through the different methods/objects.

Your first API call using the REST API Explorer

Connect to https://CLUSTER-IP_or_CVM_IP:9440/console/api/

Click on /vms and you are able to see the standard HTTP methods like GET/PUT/POST/DELETE which are used to modify/create/get VMs based on the Nutanix plattform.

vms_all_methods

Retrieve a list of all VMs which are running on Nutanix!

In this case we use the GET method to retrieve a list of all VMs which are running on Nutanix. So click on “GET /vms/”

vms_get

The Implementation Notes says: “Get the list of VMs configured in the cluster”.  This means we would get a list of ALL configured VMS if we call a “GET” using the the right URL. Okay you may ask: “What is the URL I need to send a GET to?”

URL entry points

  • For v0.8 the entry point is : https://CLUSTER-IP_or_CVM_IP:9440/PrismGateway/api/nutanix/v0.8
  • For v1 the entry point is : https://CLUSTER-IP_or_CVM_IP:9440/PrismGateway/services/rest/v1

So in this case we are using the v1 API and the URL is:

https://CLUSTER-IP_or_CVM_IP:9440/PrismGateway/services/rest/v1/vms/

So copy and paste this to the browser will show something like this:

vms_response

or you could use a tool like curl but you need to handle the authentication as well. I will talk about authentication in the second part of this tutorial.

 

But back to the REST Explorer because this can be done easier. If you scroll down in the /vms/GET you will find a button called “Try it out!” which will do exactly the same for you! Click Try it out!

vms_tryout

You will see that the format of the response which is JSON can be much better viewed now and we get some nice details!

First you will see the same URL I already showed you in the “Request URL”

Second you are able to scroll through the response and may search for the key “vmName” and the corresponding values to find all VM names. “Response Body”

Third the response Code is displayed. “200” which means: “Everything worked great” 🙂 “Response Code”

vms_tryout_output

But this lists all VMs which are configured and not only the once which are running. We would like to change this. Let’s first search the response if any key shows the actual state of the VM!

You may found a key called “powerState”.  Let’s than try to filter the response and only retrieve the VMs which are “on”.

vms_tryout_output_power

Using Nutanix FilterCriteria

For this case the we are able to use the option “filterCriteria” in the REST API Explorer to only find all VMs which are powered on. Type in “powerState==on” in the filterCriteria field and try it again.

vms_tryout_filtercriteria

vms_tryout_filtercriteria_fail

This request failed with a response code “500” and it says: “invalid filter criteria specified”. You may ask: “Why? It is exactly stated like in the response! And where the hell should I know more about this?”

The answer: “There is a KB article which shades some light here: KB 000001962”

It says for all who are note able to access the KB:

If you would like to learn more , about the filter you could use on a query, use the arithmos_cli on the CVM to get more details.

arith

In this case connect to a CVM and type:

arith_vm_power

which shows the attribute is called “power_state” instead of “powerState”. Let’s try it again with the filter criteria “power_state==on”

vms_tryout_filtercriteria_done

Boom!… It works!

This completes part 1 of this tutorial! It will get an update soon with the new API coming with the Asterix release (v2 and v3)!

If you would like to learn more about the REST API there are some resources you may have a look into:

Acropolis API Reference

Nutanix PrismAPI for Devs

Acropolis Python Tutorial

Andre Leibovici