New v4 API and SDK features in Prism Central 2024.1 and AOS 6.8

In May 2024, Nutanix released the Prism Central pc.2024.1 and AOS 6.8 software releases. These releases mark a major milestone in the Nutanix v4 API journey:

• A number of existing namespaces from Early Access (EA) status to Release Candidate (RC) status
• Additional features
• Stability improvements and bug fixes

RC APIs and SDKs can be considered closer to Generally Available (GA) compared to EA APIs.  See Nutanix v4 API Versioning Scheme for more information.  This article highlights some of the v4 API and SDK enhancements that accompany Prism Central pc.2024.1 and AOS 6.8.

Namespace Changes

The following namespaces have an updated status.

API Namespace	Previous Status	Updated Status
Cluster Management (clustermgmt)	RC1	RC2
Identity and Access Management (iam)	EA	RC
Lifecycle Management (lifecycle)	EA	RC
Networking (networking)	RC1	RC2
Prism™ (prism)	EA	RC
Virtual Machine Management (vmm)	EA	RC
Data Protection	EA	RC
Flow Management (microseg)	EA	RC
Monitoring (monitoring)	–	RC
Volumes (volumes)	–	RC
Licensing (licensing)	–	EA
Objects Storage Management (objects)	–	EA

Notes

• LCM (“lcm”) namespace has been renamed from “lcm” to “lifecycle”.
• Storage (“storage”) namespace has been deprecated. Storage management operations are now managed via the Cluster Management (“clustermgmt”) namespace.

New v4 API Features

Entity Statistics

Prism Central pc.2024.1 and AOS 6.8 introduce entity statistics via v4 API and SDK. This milestone marks one of the biggest improvements in the v4 APIs; until now virtual machine statistics were available only via the deprecated Prism Element v1 APIs. Various other entity types supported statistics via Prism Element v2.0 APIs.

Entity statistics in the v4 API namespaces move Prism Element API stats to Prism Central API stats, resulting in a more consistent and accessible experience.

The following request demonstrates the collection of all VM stats, combined with OData $select filter to limit which stats are returned.

The placeholder variables are as follows:

• $startTime – ISO-8601 date: <strong>2024-05-20T00:00:00.000000%2B10:00</strong>
• $endTime – ISO-8601 date: <strong>2024-05-20T06:00:00.000000%2B10:00</strong>
• $statType – ntnx_vmm_py_client.models.common.v1.stats.DownSamplingOperator.DownSamplingOperator.MIN
• $sampling_interval – 30
• $stat_select – stats/hypervisorVmRunningTimeUsecs

Note the URL-encoding used in start and end times (“+" replaced by "%2B").

https://{{pc_ip}}:9440/api/vmm/v4.0.b1/ahv/stats/vms/{{vm_extid}}?$startTime={{start_time}}&$endTime={{end_time}}&$statType={{stat_type}}&$samplingInterval={{sampling_interval}}&$select={{stat_select}}

The response is as follows (shortened for readability):

{
    "data": {
        "$reserved": {
            "$fv": "v4.r0.b1"
        },
        "$objectType": "vmm.v4.ahv.stats.VmStats",
        "vmExtId": "b5b580eb-547d-45f8-8c17-2b862c179057",
        "stats": [
            {
                "$reserved": {
                    "$fv": "v4.r0.b1"
                },
                "$objectType": "vmm.v4.ahv.stats.VmStatsTuple",
                "timestamp": "2024-05-19T18:50:00Z",
                "hypervisorVmRunningTimeUsecs": 7480000
            },
            ...
            {
                "$reserved": {
                    "$fv": "v4.r0.b1"
                },
                "$objectType": "vmm.v4.ahv.stats.VmStatsTuple",
                "timestamp": "2024-05-19T15:20:00Z",
                "hypervisorVmRunningTimeUsecs": 9980000
            }
        ]
    },
    "$reserved": {
        "$fv": "v4.r0.b1"
    },
    "$objectType": "vmm.v4.ahv.stats.GetVmStatsApiResponse",
    "metadata": {
        "flags": [
            {
                "$reserved": {
                    "$fv": "v1.r0.b1"
                },
                "$objectType": "common.v1.config.Flag",
                "name": "hasError",
                "value": false
            },
            {
                "$reserved": {
                    "$fv": "v1.r0.b1"
                },
                "$objectType": "common.v1.config.Flag",
                "name": "isPaginated",
                "value": false
            }
        ],
        "$reserved": {
            "$fv": "v1.r0.b1"
        },
        "$objectType": "common.v1.response.ApiResponseMetadata",
        "links": [
            {
                "$reserved": {
                    "$fv": "v1.r0.b1"
                },
                "$objectType": "common.v1.response.ApiLink",
                "href": "https://10.42.250.70:9440/api/vmm/v4.0.b1/ahv/stats/vms/b5b580eb-547d-45f8-8c17-2b862c179057?$select=stats/hypervisorVmRunningTimeUsecs,vmExtId,stats/timestamp&$statType=MIN&$startTime=2024-05-20T00:00:00.000000+10:00&$endTime=2024-05-20T06:00:00.000000+10:00&$samplingInterval=30",
                "rel": "self"
            }
        ],
        "totalAvailableResults": 1
    }
}

Our next article will cover entity stats in depth.

Batch Operations

Prism Central pc.2024.1 and AOS 6.8 introduce support for Batch Operations via API. Batch operations are aimed at environments with a need to manage large numbers of repeated, similar but not necessarily identical operations.

Batch Operations are part of the Prism (“prism”) namespace.

This release supports 4 batch operations:

• CREATE: Create entities e.g. deploy a fleet of virtual machines
• MODIFY: Update entities e.g. update the configuration of specific virtual machines
• DELETE: Delete entities e.g. delete all virtual machines meeting specific criteria
• Custom actions (will be covered in a separate article)

The following code samples are available for your reference.

• v4 API: Submit Batch CREATE Operation (Python SDK)
• v4 API: Submit Batch MODIFY Operation (Python SDK)

OData Expansion Projection

Expansion Projection allows users to request a specific entity and, at the same time, retrieve related entities. Prism Central pc.2024.1 and AOS 6.8 expand the list of namespaces and API endpoints that support expansion projection.

For example, a volume group has a related cluster entity. Information on both volume group and related cluster can be returned with a single request.The following URL demonstrates a volume group expansion projection using $expand.  This request will return a list of volumes groups as well as the related cluster and metadata.

https://{{pc_ip}}:9440/api/volumes/v4.0.b1/config/volume-groups?$expand=metadata,cluster

OData Selection Projection

Selection Projection allows users to request a specific entity or return a list of entities whilst also limiting the fields that are returned with the request.  Prism Central pc.2024.1 and AOS 6.8 expand the list of namespaces and API endpoints that support selection projection.For example, the Cluster Management (“clustermgmt”) namespace supports a request to list all clusters registered to a specific Prism Central instance. A user may wish to retrieve this list but only get the names of the registered clusters. This can be achieved with the following $select selection projection:

https://{{pc_ip}}:9440/api/clustermgmt/v4.0.b2/config/clusters?$select=name

Rate Limiting

The Prism Central pc.2024.1 and AOS 6.8 releases introduce API rate limit enforcing. These limits will be enforced when incoming requests exceed a certain limit. Further requests will be temporarily blocked. Rate limits are dictated by the Prism Central deployment size, as follows:

New & Updated Code Samples

To assist users in their migration from previous API versions to the new Nutanix v4 API standard, the following new code samples have been released. These build on the existing v4 API and SDK code samples available in the Nutanix Code Samples collection.

• v4 API: Submit Batch CREATE Operation (Python SDK)
• v4 API: Submit Batch MODIFY Operation (Python SDK)

All existing v4 API code samples have been updated to reflect the latest version of the relevant namespace.

Related Resources

• v4 API Introduction
• v4 API User Guide
• Nutanix Code Samples