Getting started with any new API can seem a little daunting, especially when you are new to API requests in general. This introductory article will cover the absolute basics – How to build and test your first Nutanix REST API request.
If you are very new to the Nutanix REST APIs and would like learn about the available versions + what each version is for, please see the following article: Nutanix API Versions – What are they and what does each one do?
What do I need?
There are an almost unlimited number of ways to setup a development environment. This is due to there being no “right” way of setting things up, combined with personal preference and environment-specific requirements.
That said, the Nutanix Developer Marketing team has prepared and recently published a complete hands-on lab named “Dev Environment Setup Lab 1.0”. This lab will walk you through the process of setting up your Linux, Mac or Windows PC/laptop so that you have the tools required to follow Nutanix labs.
If you are starting from scratch and need to install the basic requirements for development with the Nutanix APIs, it is recommended to follow this lab, first: Dev Environment Setup Lab 1.0.
To carry out your API testing you will need access to a Nutanix cluster. This can be “full” Acropolis (AOS) or Nutanix Community Edition. The requests we’ll create today are identical on both.
From a specific version perspective, this article was tested using the latest version of Nutanix Acropolis (5.11). Whenever possible and to ensure support, it is strongly recommended to use the latest version of Nutanix Acropolis on Nutanix clusters.
To carry out our API request testing we’ll use Postman. This is one of the most popular ADEs out there (API Development Environment). For our purposes, it allows the testing of authentication, GET and POST requests as well as various types of request bodies for the POST requests.
If you don’t have it installed already, please download and install Postman from the link provided.
Listing Entities – GET request
For our first Nutanix REST API request we will construct a simple GET request. This request will connect to v2.0 of the Nutanix REST APIs and ask for a list of the first 20 virtual machines on our chosen cluster.
The parameters for the example requests will be as follows:
- Cluster IP address: 192.168.1.131
- Cluster login name: admin
- Cluster password: nutanix/4u
- API version: v2.0
- Request type: GET
- JSON body or payload required: No
For Nutanix REST API v2.0 requests, the base path will be as follows:
For our specific request to list the first 20 VMs running on a cluster, that means our complete GET request will look like this:
Testing using Postman
At this point, please start the Postman application. If this is the first time you have run Postman on your system or if you have started Postman and not logged in, you won’t have any requests configured.
Note: The screenshots below show Postman version 7.5.0 running on Ubuntu Linux 19.04.
Note the two orange arrows in the screenshot.
- Arrow #1 is where we can create “Collections” i.e. saved sets of API requests. After creating our requests today we will save them for re-use later.
- Arrow #2 is where we create new tabs to manage our requests. Click the “+” button now to create a new API request tab.
The first change you’ll see when clicking the “+” button is a number of fields that need to be completed. Going through them one by one, the ones we need to focus on are as follows.
- The dropdown box labelled “GET” is where we can set the request type. For this request, “GET” is already correct. However, we could select “POST” for creating entities, for example.
- The “Authorization” tab is where we will configure our request credentials. The Nutanix REST APIs require all requests to be authenticated with a username and password combination.
- The “Headers” tab. All Nutanix REST APIs requests expect a Content-Type of “application/json”. For raw requests like the one we’re building now, we will configured this here.
- The field that currently says “Enter request URL” is where we’ll enter the API request path mentioned above.
- The “Body” tab is where we can specify an HTTP request body, often referred to as the “payload”. For our examples, request bodies are parameters that are sent along with a POST requests and will specify the settings for that request, e.g. the name of a new VM to be created.
- Lastly, the “Send” button submits our requests so it can be processed by the Nutanix cluster.
For this first GET request, follow the steps below.
- Enter our complete request URL into the field labelled “Enter request URL”. Our complete request is as follows: https://192.168.1.131:9440/api/nutanix/v2.0/vms. If you are following this in your own environment, remember to change 192.168.1.131 to the IP address of your cluster.
- Click the “Authorization” tab, change the Type to Basic Auth, then enter the username and password for your environment in the Username and Password fields. For our test, the username is “admin” and the password is “nutanix/4u”.
- Click the “Headers” tab. Click in the first column and enter the key as “Content-Type”. In the Value column, enter “application/json”. As you type into each column, you’ll see Postman auto-complete with suggested values.
- Because we are submitting a GET request this time, the “Body” tab can be ignored for now.
- Click the “Send” button.
Looking At The Response
Assuming there are no network or authentication errors in your request, Postman will return a JSON-formatted response. This response will contain some high-level information showing the number of virtual machines in the cluster. In the response we’ll see shortly, we have 5 VMs in our demo cluster. This does not include the cluster’s controller virtual machine(s)!
Let’s take a look at the response as it appears in Postman.
Each of the numbered sections are as followed, respectively.
- Our Nutanix REST API v2.0 GET request to list all virtual machines in the cluster returned a grand total of 5 VMs.
- The first VM in the response is named “CentOS 7 Client”.
- The second VM in the response is named “CI 044”.
If we were to scroll further down the request, we would see 3 more VMs named “CentOS7Vanilla”, “CentOS 7 Repo Server” and “CentOS7WithCloudInit”.
Online JSON Parsing Tools
Depending on your experience with JSON-formatted data, this layout and response may seem a little daunting. To make this a little easier, there are many online tools that allow JSON data to be parsed and read in a much easier way. One of the most popular is JSON Editor Online.
Never take data from a sensitive or confidential environment and submit it to ANY public service! This includes JSON Editor Online.
Phew, with that disclaimer/warning out of the way, let’s move on. In all seriousness, though, the risks of sending environment-specific information to a public/online service should be thoroughly considered.
There is no sensitive or confidential information in our response so let’s complete a quick additional test. Opening JSON Editor Online and pasting in the complete JSON response will allow us to browse and analyse the JSON response in an easily-digestable format. Our example is shown in the screenshot below.
You’ll see above that the exact same information is available.
Saving The Request
As mentioned earlier, Postman can be used to save requests for later use. This is a very useful featured as some requests can take some time to prepare – starting from scratch would be particularly inefficient. Saved requests can also be saved in groups e.g. for Nutanix v2.0 APIs, Nutanix v3 APIs and so on.
For our article today, the orange “dot” on the right side of the request tab indicates the request is not yet saved.
Pressing Ctrl-S (Linux/Windows/PC) or Cmd-S (Mac) will display a popup where your request’s details can be added.
- Enter a descriptive name for the request, e.g. Nutanix REST API v2.0 – List first 20 VMs
- Enter an optional desccription
- Click the Create Collection button to group your requests into a manageable structure. The screenshot below shows a collection named Nutanix API Examples that I use for my requests.
- After selecting your new collection, hit the renamed Save button and your request will be available next time you start Postman.
Note: Postman, aside from being a local application, also has a cloud component that allows your requests to be saved “in the cloud” (amongst many other things). If you prefer to use this option, please view the instructions on the Postman website.
What have we covered so far?
In this quick(ish) article we looked at a few key points.
- The base URL for all Nutanix REST API v2.0 GET requests
- The creation of a simple GET request to list the first 20 virtual machines in our demo cluster
- Testing of that request using Postman
- Processing of the JSON response using Postman and JSON Editor Online
- Saving our requests for later use
To assist you with getting used to writing your own requests, a growing collection of code samples has been provided on the Nutanix.dev Code Samples page. Covering listing and creating entities in both basic and advanced form, it is highly recommended to keep the code samples page on hand so it can be used as a reference.
While the content in this article is of an introductory nature and covers the very basics of constructing Nutanix REST API requests, the keen-eyed amongst you will have noticed two things.
- The article specifically mentioned a request that will only return the first 20 virtual machines in a cluster (even though our demo cluster only has 5). Those looking for more in-depth information that is relevant to larger environments should check out our more advanced article titled The Five Hundred (500+ VMs via v3 API).
- We only created a GET request. What if we want to make a change or create a virtual machine? Watch this space – that article is coming very soon.
Thanks for reading and I hope this introductory post was useful. 🙂