Google has made multi-versioning of its Compute Engine API generally available, introducing immutable date-stamped API versions alongside the existing /v1 surface. Starting with version 2026-09-01, the scheme lets callers choose a specific version via a request header or query parameter, while requests that name no version continue to use /v1, which has no end-of-life date.
The change responds to a problem with the /v1 endpoint, which software engineer Michael Murstein described as “a single, mutable production surface shared by every customer worldwide.” Any behavioral improvement risked breaking existing scripts or required a multi-year migration.
Now, stable versions are released quarterly with a YYYY-MM-DD format, and preview versions carry a -preview suffix with a one-year lifespan. A caller selects a version using the X-Goog-Api-Version header or the $apiVersion query parameter on the same /compute/v1/ path. Requests without a version specification continue to use /v1.
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 parameter since its REST API launched, while AWS keeps date-stamped service models inside its SDKs without exposing version selection on requests. The header-based approach mirrors the one popularised by Stripe, though Google’s quarterly cadence sits between Azure’s per-service dates and Stripe’s monthly releases.
The blog post outlines three differences a caller will notice in the date-based versions. First, the default for AggregatedList changes: /v1 returns partial results only when returnPartialSuccess is set, while the new versions enable it by default, meaning one failing zone no longer fails a fleet-wide query. Second, error bodies become structured google.rpc.ErrorInfo with reason, domain and metadata; asking for a non-existent version returns metadata listing the valid ones. Third, permissions: the new versions let Compute Engine “tighten overly broad legacy IAM permission checks and introduce safer configuration defaults” and begin moving “decade-old resource schemas” toward Google’s API Improvement Proposals.
Most users will encounter the change through tooling rather than raw headers. Each client library release for Python, Go, Java, Node.js, C#, Ruby and PHP now binds to one date-based version while keeping existing namespace names, so import paths remain unchanged. Preview SDK releases carry the preview versions. The gcloud compute command targets the bundled stable version, and a new gcloud preview compute group targets the preview bundle. The Terraform google provider targets stable versions and google-beta targets preview, with no version setting required in HCL. Discovery documents are published per version.
Both 2026-09-01 and 2026-10-01-preview are available in all regions today. Google has given no end-of-life date for /v1, no path for preview versions becoming stable, a full list of behavioral differences beyond those cited, or a statement on whether other Google Cloud APIs will adopt the same scheme.
Analysis
Why This Matters
- Developers can now pin a specific API version and avoid unexpected breaking changes, reducing risk in production deployments.
- The move aligns Compute Engine with modern API versioning practices, giving teams more confidence when upgrading tooling or infrastructure.
- The gradual tightening of IAM permissions and resource schemas may eventually reduce the need for the mutable /v1 surface, though no timeline has been given.
Background
Google Cloud’s Compute Engine API has long relied on a single /v1 endpoint that was mutable, meaning any change to behavior, such as fixing a default or updating an error format, could break existing callers. This forced a trade-off between improving the API and maintaining backward compatibility. With the new versioning scheme, each quarterly stable version is a locked snapshot of all generally available features, preventing breaking changes after release. Preview versions enable testing of upcoming changes with a limited one-year lifespan. The approach follows Google’s internal API Improvement Proposal AIP-185.
What to Watch
- Whether Google extends the date-based versioning scheme to other Google Cloud APIs, such as Cloud Storage or BigQuery.
- The adoption rate among developers, whether many will move from /v1 to pinned versions, especially given the default remains unchanged.
- Any announcement of an end-of-life date for /v1, which Google has not yet provided.
Checked
12 claims in this story checked against 1 source: 12 supported.
Show each claim
- SupportedGoogle has made immutable, date-based Compute Engine API versions generally available.InfoQ: “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.”
- SupportedThe scheme lets developers pin stable API snapshots.InfoQ: “Each stable version is a locked snapshot of all generally available features and defaults at that date”
- SupportedThe first stable version is 2026-09-01.InfoQ: “Stable versions are named YYYY-MM-DD and released quarterly, starting with 2026-09-01”
- SupportedCallers can select a version using a request header or query parameter.InfoQ: “A caller selects one with the X-Goog-Api-Version header or the $apiVersion query parameter on the unchanged /compute/v1/ path”
- SupportedRequests that specify no version continue to use /v1, which has no end-of-life date.InfoQ: “a request that names no version keeps getting /v1, which has no end-of-life date.”
- SupportedMichael Murstein described /v1 as “a single, mutable production surface shared by every customer worldwide.”InfoQ: “Because it "was a single, mutable production surface shared by every customer worldwide,"”
- SupportedBehavioral improvements to /v1 risked breaking existing scripts or requiring a multi-year migration.InfoQ: “any behavioral improvement, "even changing a counter-intuitive default or modernizing an error format," risked breaking existing scripts or required a multi-year migration.”
- SupportedStable versions are released quarterly, while preview versions have a one-year lifespan and a -preview suffix.InfoQ: “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.”
- SupportedIn date-based versions, AggregatedList returns partial results by default, so one failing zone no longer fails a fleet-wide query.InfoQ: “the date-based versions turn it on, so one failing zone no longer fails a fleet-wide query.”
- SupportedError bodies become structured google.rpc.ErrorInfo, and an invalid version request returns metadata listing valid versions.InfoQ: “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.”
- SupportedNew versions let Compute Engine tighten legacy IAM permission checks and move decade-old resource schemas toward Google's API Improvement Proposals.InfoQ: “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”
- SupportedGoogle is the last of the three largest cloud providers to let callers pin an API version on a request.InfoQ: “With this release, Google is the last of the three largest cloud providers to let callers pin an API version on a request.”
