Google Cloud has made multi-versioning of the Compute Engine API generally available, adding immutable, date-stamped API versions beside the long-lived /v1 surface. Stable versions are named YYYY-MM-DD and released quarterly, starting with 2026-09-01; preview versions carry a -preview suffix and a one-year lifespan. A caller selects one with the X-Goog-Api-Version header or the $apiVersion query parameter on the unchanged /compute/v1/ path, and a request that names no version keeps getting /v1, which has no end-of-life date.
Software engineer Michael Murstein writes that the problem was the shape of /v1 itself. Because it "was a single, mutable production surface shared by every customer worldwide," any behavioral improvement, "even changing a counter-intuitive default or modernizing an error format," risked breaking existing scripts or required a multi-year migration. Google calls the replacement interface-based versioning, aligned with its own AIP-185, which requires stable versions to be dates and previews to be time-bound. Each stable version is a locked snapshot of all generally available features and defaults at that date, and no breaking change is made to it after publication.
The blog post names three differences a caller will notice:
- A default: /v1 returns partial results from AggregatedList only when the request sets returnPartialSuccess, and the date-based versions turn it on, so one failing zone no longer fails a fleet-wide query.
- The error body, which becomes structured google.rpc.ErrorInfo with reason, domain and metadata; ask for a version that does not exist and the metadata lists the ones that do.
- Permissions. Murstein says new versions let Compute Engine "tighten overly broad legacy IAM permission checks and introduce safer configuration defaults" and start moving "decade-old resource schemas" toward Google's API Improvement Proposals, while automation pinned to /v1 sees none of it.
Most callers will meet the change through tooling rather than headers. Each client library release for Python, Go, Java, Node.js, C#, Ruby and PHP now binds to one date-based version while keeping the compute_v1 and apiv1 namespaces, so no import paths change, and -preview SDK releases carry the preview versions. gcloud compute targets the bundled stable version and a new gcloud preview compute group targets the bundled preview, with existing compute, beta and alpha scripts unchanged. The Terraform google provider targets stable versions and google-beta targets preview, with no version setting in HCL. Discovery documents are published per version.
With this release, Google is the last of the three largest cloud providers to let callers pin an API version on a request. Azure Resource Manager has required a date-stamped api-version query parameter, with a -preview suffix for previews, since its REST API launched, while AWS keeps date-stamped service models inside its SDKs and does not expose version selection on a request. The header form Google chose is the one Stripe popularized outside the cloud market; its Stripe-Version header now takes values such as 2026-10-28.endive, with monthly releases that carry no breaking changes and a major release twice a year that may. Google's quarterly cadence sits between Azure's per-service dates and Stripe's monthly ones, and unlike Stripe it has not said which quarterly versions will carry breaking changes relative to the previous one.
Google gives no end-of-life date for /v1, no path by which a preview version becomes stable, no complete list of behavioral differences between /v1 and 2026-09-01 beyond the examples above, and no statement on whether other Google Cloud APIs will adopt the scheme; the /beta and /alpha channels are not mentioned. Both 2026-09-01 and 2026-10-01-preview are available in all regions today.