Nutanix v4 APIs: Getting Entity eTag

Back in 2022, the majority of Nutanix v4 APIs were early access (EA). With the recent updates to release candidate (RC) across various namespaces, a number of functional changes have been made. This article covers the improvements in retrieving an entity’s eTag, a version identifier that ensures concurrent requests don’t result in unexpected configuration mismatches.

How did this work before?

In previous versions, entity eTags were returned via the response header. For example, this API request asks to list images, filtered by those with a name containing the string “CentOS”.

https://{{pc_ip}}:9440/api/vmm/v4.0.b1/content/images?$filter=contains(name, 'CentOS')

The response is a filtered list of images which can then be used to get image details, including each image’s unique ID (extId). Part of the response from our demo environment is as follows:

{
    "data": [
        {
            "$reserved": {
                "$fv": "v4.r0.b1"
            },
            "$objectType": "vmm.v4.content.Image",
            "sizeBytes": 8589934592,
            "createTime": "2024-01-30T04:54:50.191104Z",
            "lastUpdateTime": "2024-01-30T04:54:50.191104Z",
            "ownerExtId": "f0b701e7-163d-5358-abbc-2edb73b1a38c",
            "extId": "`",
            "name": "CentOS-7-x86_64-GenericCloud-2211.qcow2",
            "type": "DISK_IMAGE"
        }
    ],
    ...
        "totalAvailableResults": 1
    ...
}

This specific request returns a list containing a single image; that image’s unique ID (extId) is ffa90cb0-e151-4672-be86-059d5ed110ae. A subsequent request for that specific image would be:

https://{{pc_ip}}:9440/api/vmm/v4.0.b1/content/images/ffa90cb0-e151-4672-be86-059d5ed110ae

For this article we don’t need to worry about the image’s configuration. However, in the response headers we see the following key/value pair:

Etag: YXBwbGljYXRpb24vanNvbg==:0

While this eTag could be easily retrieved by parsing the response headers, the latest Nutanix v4 APIs make this much easier.

Get Image eTag (Python)

For this request we’ll use Python to demonstrate the retrieval of the image’s eTag. Note, however, that all Nutanix v4 SDKs include the same type of function.

Note: An entity’s eTag is still returned in the response headers so could be parsed manually. However, a suggested method is as follows:

# Use the Nutanix v4 APIs to request a specific image then retrieve the image's unique ID (extId)

import ntnx_vmm_py_client
from ntnx_vmm_py_client import Configuration as VMMConfiguration
from ntnx_vmm_py_client import ApiClient as VMMClient
from ntnx_vmm_py_client.rest import ApiException as VMMException

# consider the implications of disabling certificate verification in a production environment
import urllib3

urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

# setup the configuration
config = VMMConfiguration()
config.host = "0.0.0.0"
config.port = "9440"
config.username = "prism_central_username"
config.password = "prism_central_password"
# consider the implications of disabling certificate verification in a production environment
config.verify_ssl = False

vmm_client = VMMClient(configuration=config)

# image management function are provided by the ImagesApi
vmm_instance = ntnx_vmm_py_client.api.ImagesApi(api_client=vmm_client)

# build a list of images, filtered by name
# alter this filter to suit your environment
print("Building image list ...")
images_list = vmm_instance.list_images(
    async_req=False, _filter="contains(name, 'CentOS')"
)

# request details about the first image in the list
# check that the list isn't empty, first
if images_list.data:
    print(f"{len(images_list.data)} image(s) found.  Requesting first image ...")
    try:
        existing_image = vmm_instance.get_image_by_id(images_list.data[0].ext_id)
        # get the image's eTag
        print(
            f"Image with extId {images_list.data[0].ext_id} retrieved, getting image eTag ..."
        )
        existing_image_etag = vmm_client.get_etag(existing_image)
        print(f"Image eTag: {existing_image_etag}")
    except VMMException as ex:
        print("An exception has occurred while retrieving this image")
        print(f"HTTP status: {ex.status}")
        print(f"Details: {ex.body}")
else:
    print("No images found.")

Shown below is a screenshot of how this looks when run.

Why retrieve an entity’s eTag?

The Nutanix v4 APIs require each entity’s eTag to be sent as the value of the If-Match header when making an update request. This ensures concurrent requests don’t clash and result in unexpected results.

For a complete guide to using eTag with Nutanix v4 APIs and SDKs, see Using ETag and If-Match Headers with Nutanix v4 APIs.

Conclusion

While simple, the provision of simple functions such as get_etag (Python) makes the Nutanix v4 API consumption easier and more efficient.

Related Resources

• Nutanix Nation on X – follow us here so you don’t miss any updates
• Nutanix.dev – Resources for the Nutanix technical community
• Nutanix.dev code samples
• NutanixDev on GitHub
• Nutanix Developer Portal – Official v4 API documentation