- Nutanix REST API with Golang/Go Tutorial – Part 1 – Nutanix REST API Overview
- Nutanix REST API with Golang/Go Tutorial – Part 2 – Authentication
- 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
Introduced with AOS >= 5.0 but not GA yet
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
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.
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/”
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:
So copy and paste this to the browser will show something like this:
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.
curl --user admin:nutanix/4u --insecure -H "Content-Type: application/json" -H "Accept: application/json" https://192.168.178.130:9440/PrismGateway/services/rest/v1/vms/
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!
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”
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”.
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.
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.
In this case connect to a CVM and type:
arithmos_cli list_attributes_and_stats entity_type=vm |grep power
which shows the attribute is called “power_state” instead of “powerState”. Let’s try it again with the filter criteria “power_state==on”
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: