I was asked recently to take a look at an API issue around uploading an image file from a desktop directory location into the Acropolis Image Service. The REST calls for this workflow are part of version 0.8 of the Nutanix Management API. As such they only work on an endpoint supplied by Prism Element.
We covered image upload briefly in a previous post were we touched upon uploading from an external URL. The mechanism for image upload discussed here is in two parts. The first requires a POST call that will populate the image entry in the repository with the various metadata. For example, name, image type and so on. The second phase is the actual “image binary data” upload and this is done via a PUT call. Once both parts are successfully returned, we have the fully completed image. Let’s start with the initial POST call to upload a small CirrOS cloud image, in which we specify a name for the image and its image type (imageType).
The resulting task UUID could be monitored for progress and status if required. However, the operation often completes before we get the chance. Next we review the returned JSON response from a REST call listing all current images. The imageState at this point is currently INACTIVE. It needs to be in this status for the subsequent update or PUT step to proceed.
In order to load the image data to its previously created metadata, we need both the current image UUID and the UUID of the storage container we will upload the image to. The image UUID we already have from the /images call above. We can do similar to GET the storage container UUID
The Nutanix API dev team are continually working on making improvements to our REST automation capabilities. If this is something that interests you then feel free to reach out with any suggestions. Maybe you want be able to take a first look at our latest API innovations or help drive those changes with feature requests? In either case, please reach out to us to get the ball rolling.
In this post I used api/nutanix/v0.8 and api/nutanix/v2.0 in my base/endpoint URLs. While the defined endpoints in older documentation are PrismGateway/services/rest/v[0.8,2.0]/, there has been a move (within REST Explorer) to standardise on a single endpoint syntax while still calling out the version of API albeit v0.8 or v2.0. Both base url formats are interchangeable, however I recommend you always stick to the latest format for sake of consistency.
For the non European football fans out there, Kenny Dalglish,or “King Kenny” as he was known to both the Liverpool and Celtic faithful, was once described in a match commentary as “the creator supreme”. In this short series of posts covering the REST capabilities for managing the Nutanix Enterprise Cloud, I hope to show its possible that we can all be a “creator supreme” just like King Kenny!
The first place to look when working with the API is the REST API Explorer itself. You invoke the Explorer page by right-clicking the admin pull-down menu (top right of Prism home page) and selecting the REST API Explorer option.
It’s good practice to create a separate user login for the REST Explorer. The REST API Explorer is essentially the documentation to the API. It’s produced via swagger, which is an open standard that takes your API spec and generates interactive documentation. The documentation can be viewed and you are able to interactively test API calls via a browser.
Let’s start by taking a look at a simple POST method that will list all currently available images:
Select the above method in the images section of the REST API Explorer to expand the method details:
In order to try out the REST method, double click on the Model Schema box (right hand side above) – this will then be populated into the get_entities_request box on the left hand side. You can edit the entities according to how you want to retrieve the available information. For example here’s the bare minimum you need as a JSON payload to request information from the Images catalogue.
Note that with our pagination we are starting at offset zero – so the first image – until the tenth image, defined by the length parameter. With the JSON payload entered as above we can press the Try it out! button and see the method in action.
The results of the method call are displayed below. The Curl syntax for invoking the method and json payload are shown, along with the individual Request URL and the Response Body. We can use the Curl syntax to programmatically call the method outside of the Explorer, either in Bash or Python, for example.
Once we begin to use the methods independently of the Explorer, then in addition to curl you should consider installing a JSON command line processor like jq, and use a JSON Linter to validate your JSON syntax for data payloads. How the tools might be used will be shown throughout this post
Lets recap the previous POST method but this time run it from the command line. In this instance we load the JSON payload (see above) from the file list_images_v3.json using the -d option. The -k option , or — insecure allows the command to proceed even though I am using self-signed SSL/TLS certs. The -s option simply disables all progress indicators.
Piping the output from the curl command into jq, provides a formatted and syntax highlighted output that’s easier to read. To make this more obvious, let’s use some additional options to the jq command line and pull out just one image reference:
One of the prime uses for this kind of command is to retrieve only the info required when populating a schema for another REST method (see below shortly). For example, you may only want a subset of entries and perhaps they need to be conveniently labelled:
Notice the PENDING status in the output above. We can follow the progress of the image upload by using the task_uuid entry in a tasks method call. The call can be run again and again until a task, in this case the upload, is complete
Hopefully this will help get people started on their API path, we haven’t really scratched the surface of what can be done. Hopefully, this post has at least demystified where and how to make a start. In subsequent posts I hope to show more ways to glean info from the API Explorer itself and how to use it to build more complex REST methods. Until then, check out Nutanix Developer Community site. Good luck creators!