Using Request ID Headers with Nutanix v4 APIs

With the Nutanix v4 APIs now released as Early Access (EA), the options for managing and creating entities in a Nutanix Prism Central environment have significantly improved. For example, the current EA release, available through Prism Central version pc.2022.6, allows API consumers to create images that will be used as base disks for new VMs. An important note at the time of writing this article is that VM CRUD operations themselves are still under development and will be made available in an upcoming release. However, images created using the current EA APIs can be used during the VM creation process.

When consuming the Nutanix v4 APIs via HTTP endpoints, there is a key difference between how requests are submitted now vs how they were submitted using previous Nutanix REST API versions.

Image creation using Nutanix API v3

A simple image creation request using the Nutanix Prism Central v3 APIs would include components similar to those shown below.

• URL: https://{{pc_ip}}:9440/api/nutanix/v3/images
• Type: POST
• Payload: JSON formatted specification that defines various image components e.g. name, source URL, description
• Headers: Single mandatory header Content-Type: application/json.

In the context of this article, it is the single mandatory header that is now different.

Image creation using Nutanix API v4

An image creation request using the Nutanix Prism Central v4 APIs is similar but with a couple of key differences. Note v4.0.a1 is the current EA API version and will likely change in future versions.

• URL: https://{{pc_ip}}:9440/api/vmm/v4.0.a1/images
• Type: POST
• Payload: JSON formatted specification that defines various image components e.g. name, source URL, description, object type
• Headers: Two mandatory headers, Content-Type: application/json and Ntnx-Request-Id.

Ntnx-Request-Id is an idempotency identifier and must be specified as a UUID.

What if the Ntnx-Request-Id header is missing?

Because this is a mandatory header, omitting it from a v4 API entity creation request will result in an error similar to the following. This example is the response from attempting to create a Prism Central image.

{
    "$dataItemDiscriminator": "vmm.v4.error.ErrorResponse",
    "data": {
        "$errorItemDiscriminator": "List<vmm.v4.error.AppMessage>",
        "error": [
            {
                "message": "Failed due to error while performing the operation as the request Id is invalid/missing.",
                "severity": "ERROR",
                "code": "VMM-20601",
                "locale": "en_US",
                "$reserved": {
                    "$fqObjectType": "vmm.v4.r0.a1.error.AppMessage"
                },
                "$objectType": "vmm.v4.error.AppMessage"
            }
        ],
        "$reserved": {
            "$fqObjectType": "vmm.v4.r0.a1.error.ErrorResponse"
        },
        "$objectType": "vmm.v4.error.ErrorResponse"
    },
    "$reserved": {
        "$fqObjectType": "vmm.v4.r0.a1.images.ImagesTaskApiResponse"
    },
    "$objectType": "vmm.v4.images.ImagesTaskApiResponse"
}

Take note of the error message detail: “Failed due to error while performing the operation as the request Id is invalid/missing.“

How to use Ntnx-Request-Id header

From a programmatic perspective there are multiple ways to generate a UUID suitable for use with the Ntnx-Request-Id header. Some examples are shown below.

# generate UUID with Python 3
import uuid
uuid_example = uuid.uuid1()
print(uuid_example)

# generate UUID with PowerShell
$uuid_example = [System.Guid]::NewGuid().ToString()
Write-Output $uuid_example

# generate UUID with Bash Shell
export uuid_example=`uuidgen`
echo $uuid_example

However, in situations where code cannot be used to generate a UUID, online tools such as https://www.uuidgenerator.net/ can be used. UUIDs used in this manner are single use only.

In the screenshot below, Postman has been used to demonstrate Ntnx-Request-Id header usage.

A complete example of working image creation JSON payload is available here at v4 API: Create Prism Central Image.

What if I re-use the Ntnx-Request-Id header?

Re-using a previously submitted idempotency identifier for the Ntnx-Request-Id header will result in a successful API request. However, the API response will reflect the previously-submitted task’s result and will not initiate a new task.

Is the Ntnx-Request-Id header required for other entity creation API endpoints?

Yes. Image creation has been used as an example only. Expect other entity creation and update requests e.g. VM creation or update to require the same header usage demonstrated here.

Is the Ntnx-Request-Id header required with the Nutanix v4 SDKs?

No. The Nutanix v4 SDKs automatically generate and submit the Ntnx-Request-Id header for you. Users should not manually specify or add the Ntnx-Request-Id header to requests submitted via the Nutanix v4 SDKs.

Wrapping Up

As we develop the Nutanix v4 APIs, please expect EA APIs and documentation to change. Announcements about new versions and updates will be made here on Nutanix.dev so stay tuned for updates in the near future.

Thanks for reading and have a great day! 🙂