Nutanix API v3 vs v4: What Changed and How to Plan a Migration

Most Nutanix environments with any automation history have v3 code in them somewhere: a provisioning script, a CMDB sync, a reporting job that has quietly run for years. The v4 APIs are now the recommended interface, which raises an uncomfortable question. Does all of that need rewriting?

The short answer is no, not urgently, and not all at once. But understanding what actually changed will tell you which parts to move first.

Applies to: Prism Central v4 GA APIs alongside the legacy v3 API. This post assumes familiarity with basic v4 request structure, covered in Getting Started with the Nutanix v4 REST APIs.

The core difference: intent versus resources: The v3 API is built around an intent model. You describe a desired spec, Prism Central reconciles it, and a status block reports what actually exists. Queries are performed by posting a body to a list endpoint.

POST /api/nutanix/v3/vms/list
{
  "kind": "vm",
  "length": 20
}

The v4 API is resource-oriented and namespaced. Reading a collection is a GET, and the query lives in the URL.

GET /api/vmm/v4.0/ahv/config/vms?$limit=20

That single change has consequences throughout your code. Caching, logging, proxies, and API gateways all treat a GET differently from a POST, and a URL-based query is far easier to reproduce from a log line than a request body you no longer have.

Side by side

Concern	v3	v4
Model	Intent, spec plus status	Resource-oriented, namespaced
Listing	POST …/list with a body	GET with query parameters
Filtering	Filter criteria in the payload	OData $filter, $orderby, $select
Concurrency	spec_version carried in the payload	ETag supplied via If-Match
Idempotency	Not built in	Ntnx-Request-Id header
Contract	Documented per endpoint	OpenAPI 3 with generated SDKs

Two-column comparison of the Nutanix v3 and v4 APIs across list requests, request model, filtering, concurrency control, idempotency, and API contract.

The last row matters more than it looks. Because v4 is defined by an OpenAPI specification, the SDKs for Python, Java, Go, and JavaScript are generated from the same source as the documentation. The client library and the reference cannot drift apart the way hand-maintained wrappers do.

Namespaces replace one large surface: In v3 you largely worked against a single API surface. In v4, functionality is divided into namespaces: vmm, clustermgmt, networking, iam, prism, dataprotection, and others.

A v3 script that touched VMs, subnets, and clusters in one flow becomes a v4 script that talks to three namespaces. If you use the SDKs, that means three client packages. This is not extra work so much as newly visible work: those were always three different concerns.

Writes are stricter now: This is the change most likely to break a naive port. In v4, modifying an existing entity requires the current ETag, sent as an If-Match header, and most create, update, and delete requests require an Ntnx-Request-Id header carrying a UUID.

These are not optional conveniences. A write without them is rejected. If your v3 code performed a blind update using a payload it assembled from a much earlier read, that pattern does not survive the move, and arguably it should not have survived in v3 either.

The mechanics of ETags, request identifiers, and the asynchronous tasks that writes produce are involved enough to deserve their own post, which is the next in this series.

A staged migration: Rewriting everything in one project is the approach most likely to stall. A staged sequence works better:

Inventory what you actually have. Search your repositories for /api/nutanix/v3/ and for Prism Element v2.0 paths.
Classify each call as read or write. Reads are low risk and can move first.
Confirm coverage. Check that the v4 equivalent exists and is GA in your Prism Central release before committing to a rewrite.
Port reporting and inventory jobs. These deliver the OData filtering benefit immediately with little risk.
Port writes individually, with the ETag and request-identifier handling built in from the start.
Retire the v3 credentials and paths only after the replacement has run through a full cycle.

Running both versions during transition is expected and supported. v3 remains available until formal deprecation, so there is no cliff edge forcing a rushed cutover.

Where v3 may still be required: Coverage has expanded steadily, but v4 namespaces have reached general availability at different times across releases. Some product-specific functionality may still only be reachable through a legacy API on your version.

Check before you plan, not after. A migration plan that assumes complete parity and discovers a gap halfway through is worse than one that documents the exceptions on day one.

It is also worth remembering that v2.0 is a Prism Element API. Some cluster-local operations live there rather than in Prism Central, so “migrate everything to v4” is not always a statement about one API surface.

Summary: v4 replaces the intent model with resource-oriented, namespaced endpoints, moves filtering into OData query parameters, and enforces ETags and request identifiers on writes. The result is more predictable and stricter.

Migrate reads first, writes deliberately, and verify v4 coverage for your specific release before committing. There is no need to rewrite working v3 automation on a deadline that does not exist.

Series Links: