So many variables! How I test Nutanix APIs with Postman

So many variables ... How I test Nutanix APIs with Postman

Hi, I’m Chris. 🙂 A couple of my colleagues have written pieces on various DevOps-y things lately but, the rest of the time, “I” refers to me. Lol.

Anyway, I do a lot of work with the Nutanix REST APIs. Part of that is sharing things I find with you, our valuable readers out there in the real world. Whenever something useful comes up, I tend to write an article about it; today is no different.

Those with experience in working with APIs will have heard of and be familiar with Postman, the ubiquitous API testing and development tool. However, there’s plenty of content on the Nutanix Developer Portal that is aimed at those just starting out with the Nutanix REST APIs, including setting up your first request. Today’s article will cover how I setup my testing environment to make that testing quick and easy.

Step 1 – Get Postman

This is a bit of a no-brainer. If you don’t have it already, head on over to https://getpostman.com, download the version most appropriate for your operating system (I use Ubuntu Linux 19.04 and the Cinnamon Desktop Environment) and get it installed. Don’t worry about customising the install or settings just now – we’ll go through some of that in a bit.

Step 2 – Basic Settings

Here I’ll go through some of the basic changes I make as soon as Postman is installed. To get to these settings, click the Postman settings icon (it looks like a spanner) and select Settings.

Postman “Settings” option
  • Enable the Dark Theme. I’m not usually a fan of Dark Mode in any environment, not even at night. However, Postman is one of the few apps that looks great when configured this way. Click the Themes tab, and toggle the theme from light to dark, if you want your Postman environment to look as you see in occasional screenshots.
  • Disable SSL certification verification. On the General tab, toggle off the option labelled SSL certificate verification. Please be aware of the security implications of this change in a production environment. Why? Any and all SSL certificates will be automatically accepted, even if they aren’t valid. Those with experience using Nutanix Prism or the Nutanix REST APIs without installing a valid certificate will be aware that the default self-signed certificate is not valid in the truly trusted sense. Disabling SSL certification verification gets around Postman API requests failing when this certificate is found to be invalid.
  • Set the request timeout. By default, the request timeout is set to 0. This means every API request will wait forever if no response is received. This really isn’t a good default for us as we’d like the retain the opportunity to fix an issue and try again, if something isn’t quite right. I have mine set to 30 seconds i.e. 3000ms.
  • Disable anonymous usage data. This is optional but it’s worth being aware that this is enabled by default. In secure environments, for example, it is common for all external network activity to be blocked/banned or otherwise controlled. If your environment is considered secure, you may wish to toggle this option off.
  • Enable Two-pane view. By default, Postman’s UI is setup so the request settings is at the top and the responses appear underneath. There’s nothing wrong with this, but I prefer to have the responses appear in a pane on the right side of Postman’s UI. Perhaps it’s because of the default Google Chrome Developer Tools location?
  • Configure Proxy. In an enterprise environment, it is possible your PC/laptop/VM is behind some sort of proxy server. If you need to explicitly configure this within Postman, you can do so on the Proxy tab.

When that’s all done, here’s how my General tab looks.

Postman Settings – General tab

Step 3 – Create a Collection

Because we’re all developers of one sort or another, I’m going to assume that some level of organisation and order is second-nature to us all. With that in mind, it makes sense to create a Postman Collection with which to organise our things.

  • On the left of the Postman UI, click New Collection. Give the collection a name, Nutanix REST API Testing for example.
  • Ignore the Authorization tab for now; we’ll come back to it shortly.
  • Head over to the Variables tab where we’ll start making sure our workflow is as efficient as possible.

Step 4 – Environment Variables

One of the simplest and yet best Postman features is the ability to use variables. A good example of why this is so useful is Prism Central “vs” Prism Element. While testing various Nutanix REST API requests, it’s very common to switch between Prism Central and Prism Element, to use the same credentials for multiple requests and to use the same entity UUIDs on multiple places. Entering these manually each time and then needing to change each instance when the values change is not efficient at all. As a side note, Postman can also take your saved API requests, export them and allow you to share the request collections with colleagues. In this situation, you may not want to share specific environment settings but still allow your colleagues to enter information once and once only. The way around all these things is to use Postman Variables.

The first thing you’ll find is, as expected, we have no variables defined.

Postman collection with no variables defined

In this article, I’ll do exactly as outlined above. Prism Central and Prism Element IP addresses will both be used frequently, but both will use the same credentials. Security best practices aside, this is not entirely uncommon while testing. Note that Postman can definitely manage global variables i.e. variables available to every collection and across an entire Postman workspace. In this example I’m only defining them where they are available to a specific collection.

  • Hit the Add a new variable link and enter the variable name as pc_ip. The Initial Value will be shared with anyone you share the collection with, and can be good if everyone is using the same variable values. The Current Value isn’t synced anywhere and is available locally only. As you set the Initial Value for pc_ip, note the Current Value is also set to the same value.
  • I’ll then repeat this process for the other variables this collection needs, as shown in the table below.
Variable usageVariable nameInitial Value
Prism Central (PC) IP addresspc_ip10.133.16.228
Prism Element (PE) IP addresscluster_ip10.133.16.50
Usernameusernameadmin
Passwordpasswordnutanix/4u
CentOS 8 ISO URIcentos8_urihttp://mirror.intergrid … (long)

Step 4.1 – Using Variables

When setting up your requests, using the variables defined above is simple. Where a variable needs to be referenced, the syntax is as follows: {{variable}}. Take a look at the request below and note the Prism Central IP address hasn’t been entered directly but has instead been added via variable reference. The same thing has been done for the username and password.

Postman variable used in place of manually entering the Prism Central IP address
Postman variables being used in place of manually entering the username and password

Step 5 – Pre-request Scripts

UPDATE 2020.06.22Step 5 below has been left here for pre-request script reference only. Current versions of Postman do support variable substitution within a JSON request payload.

By default, Postman doesn’t seem to allow {{variable}} syntax within the body of a POST request. I’m sure that’s incorrect but for some reason sending a request with variables in the body like this will simply result in nothing be sent in that variable’s place. To make that work, however, a little pre-work is required in the form of a pre-request script.

Here’s a simple JSON payload for a POST request:

{
    "spec":{
        "name": "{{vm_name}}",
        "resources":{
        }
    },
    "api_version":"3.1.0",
    "metadata":{
        "kind":"vm"
    }
}

The {{vm_name}} variable won’t get substituted as you’d expect. However, heading to the “Pre-req” tab and adding this as a pre-request script fixes the issue.

var vm_name = pm.variables.get("vm_name");

postman.setEnvironmentVariable("vm_name", vm_name)

Step 6 – Import Sample Collection

An article like this wouldn’t be complete without seeing some of these things in action. With that in mind, I’ve made available a Postman collection that contains some sample Nutanix REST API requests (v1, v2.0 and v3). Let’s get that imported.

  • Head over to the NutanixDevs Github and download Nutanix REST API Testing.postman_collection.json.
  • Switch to Postman and, near the top-left of the main UI, hit the Import button.
  • Select Choose Files (or drop the file into the UI) and browse to the JSON file you just downloaded.

There’s no “OK” button at this stage so if everything was successful, you’ll see a message like this one in the bottom-right corner of the Postman UI.

Successful import of Postman sample collection

And, on the left within Collections you’ll see a number of sample API requests. For this screenshot I’ve expanded each of the branches within the new collection.

Imported Postman sample collection

This collection has a number of things pre-configured for you.

  • Authorization has been set to use collection-scope variables
  • All requests have been set to inherit their authorization from the parent i.e. the collection
  • A list of variables has been added to demonstrate how they’re used within requests (screenshot below)
Predefined collection-scope variables for use with the sample API requests

However, you’ll recall from Step 4 that the Current Value of any variable is local only and is not exported along with a collection. That’s why only a few of the variables have values currently set. Looking a bit deeper, you’ll see the variables that do have values set are those that could possibly be used across environments. For example, {{username}} could be shared during a test phase and the URI for the CentOS 8 ISO would likely be valid no matter where you’re located. The “disclaimer” there is the CentOS 8 image’s mirror is based in Australia because that’s where I live. You’ll probably want to change that by grabbing an appropriate/closer mirror URI from the CentOS website. 🙂

Beyond that, all you’ll need to is populate the variables with values that make sense for your environment.

If you decide to check out the stats request example, please be sure to check out the article entitled Getting VM Performance Metrics via API as it goes into detail on how the process works and what things like start_time_in_usecs means.

Taking things further

If your workstation/PC/laptop/VM hasn’t really been used as a development environment before, now is a great time to check out our Dev Setup lab! Written expressly for those people relatively new to development, it covers recommended tools, settings and a few customisation bits that will help make your dev efforts smoother.

The Dev Setup lab is available on the Nutanix Developer Portal Labs page.

Wrapping Up

While it’s true that Postman has many, many more features than those outlined above, configuring collections and a few variables can start you on the journey to much more efficient testing. Simply by using variables, for example, you’ve automatically saved yourself from manually altering all occurrences of an API endpoint IP address, should it change. At a higher level, you’ve also started collecting requests in both a logical and visually appealing way.

Hopefully this brief(ish) article helps you.

Thanks for reading and have a great day! 🙂

SSH PUBLIC KEY

Copy the SSH public key below.  In BASH shell environments, for example, this file could be saved to ~/.ssh/nutanix_demo.pub

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQCm+7N2tjmJw5jhPmD8MS6urZQJB42ABh73ffGQSJ0XUHgdEDfjUDFkLK0wyJCe0sF5QJnh07UQn0F0BUnBi+VwehPGeODh6S43OP5YS/14L0fyntFI06B9lckx/ygRNu82sHxXCX+6VVUFPOPC+sz6j1DQswKY9d4cEYnaMBGSzqRxrqAIf6aWIKTJTYKPFY0zaUZ6ow2iwS0Nlh5EqaXsEBWkqMmr7/auP9GV/adUgzFrGLJklYBdfH575SIK6/PZL6wNT0jE9LmFlEm7dI01ZWPclBuV16FzRyrnzmWr/ebY62A04vYBtR0vyfEfsW2ZgxgD6aAE6+ytj0v19y0elRtOaeTySN/HlXh7owKWCHnlXNpTUiSDP8SQ8LRARkhQu3KEDL0ppGCrSF87oFkp1gPzf92U+UK3LaNMMjZXMOy0zLoLEdLtbQo6S8iHggDoX4NI4sWWxcX0mtadvjy/nIOvskk9IXasQh0u0MT9ARQY5VXPluKDtEVdeow9UbvgJ1xxNkphUgsWjCiy+sjgapsuZvWqKM6TPT1i24XYaau+/Fa0vhjLb8vCMWrrtkRwGt4re243NDYcYWTzVZUFuUK0w1wqt77KgjCCeyJdsZNwrh15v780Fjqpec3EGVA0xyNbF0jn/tsnYy9jPh/6Cv767EratI97JhUxoB4gXw== no-reply@acme.com