Dev News Daily ENDE

Google Compute Engine adds dated API versions next to /v1, with new defaults on opt-in

Google Cloud has made multi-versioning of the Compute Engine API generally available, InfoQ reported on 14 November. Next to the long-lived /v1 surface, callers can now choose immutable versions named by date. Stable versions follow the YYYY-MM-DD pattern and are released quarterly, starting with 2026-09-01; preview versions carry a -preview suffix and live for one year.

A caller picks a version with the X-Goog-Api-Version header or the $apiVersion query parameter, on the same /compute/v1/ path as before. A request that names no version still gets /v1, which has no end-of-life date. Each stable version is a locked snapshot of every generally available feature and default as of its date, and Google says no breaking change will be made to it after publication. The scheme follows Google's API Improvement Proposal AIP-185.

The reason, according to a Google blog post by software engineer Michael Murstein that InfoQ quotes, is that /v1 was one mutable production surface shared by every customer. Fixing even a counter-intuitive default or modernising an error format risked breaking someone's scripts or needed a multi-year migration.

The post names three differences callers will see in the new versions. AggregatedList returns partial results by default, where /v1 does so only when returnPartialSuccess is set, so one failing zone no longer fails a fleet-wide query. Errors become structured google.rpc.ErrorInfo objects with reason, domain and metadata, and asking for a version that does not exist returns the list of versions that do. And new versions let Compute Engine tighten overly broad legacy IAM permission checks and move old resource schemas toward the AIPs, while automation pinned to /v1 sees none of these changes.

Most users will meet the change through tooling. Client library releases for Python, Go, Java, Node.js, C#, Ruby and PHP now each bind to one dated version while keeping the compute_v1 and apiv1 namespaces, so import paths do not change. gcloud compute targets the bundled stable version and a new gcloud preview compute group targets the preview. The Terraform google provider targets stable versions and google-beta targets preview, with no version setting in HCL. Discovery documents are published per version.

Google Compute Engine adds dated API versions next to /v1, with new defaults on opt-in
Google Compute Engine adds dated API versions next to /v1, with new defaults on opt-in — Dev News Daily

Why it matters

Upgrading a client library now changes API behaviour, not only code. A team that bumps the Python or Go library will get partial results and stricter IAM checks with it, which is good for correctness but worth testing, because a fleet-wide query that used to fail loudly will now succeed with missing zones.