Cloud Computing
Google Cloud Launches Date-Based Versioning for Compute Engine API
Google has introduced immutable, quarterly date-stamped versions of its Compute Engine API alongside the legacy v1 endpoint to enable safer changes without breaking customer workloads.
InfoQ
Google Cloud has introduced a new versioning model for its Compute Engine API, rolling out immutable, quarterly date-stamped versions that sit alongside the long-standing /v1 endpoint. This approach lets the company evolve the API more freely while keeping existing integrations intact.
The Problem with a Single Mutable Version#
The v1 API served as a shared, mutable surface for all Google Cloud customers worldwide, creating a tension between stability and improvement. Even modest enhancements—adjusting counterintuitive defaults or modernizing error formats—risked breaking legacy scripts or demanded years-long migration paths. The new versioning scheme addresses this by locking API behavior to specific points in time.
How the New Versioning Works#
Stable versions follow a YYYY-MM-DD naming convention and release quarterly, starting with 2026-09-01. Preview versions carry a -preview suffix and expire after one year. Callers specify their preferred version using either the X-Goog-Api-Version header or a $apiVersion query parameter; requests that omit a version default to /v1, which has no end-of-life date.
Each stable version becomes a frozen snapshot of all generally available features and defaults at that date. Once published, no breaking changes are applied to it—a guarantee that helps teams maintain confidence in their integrations across time.
Behavioral Differences from the Current v1#
The new versioning introduces several observable changes:
- Partial results handling: The current /v1 requires explicit opt-in to return partial results when using AggregatedList. Date-based versions enable this by default, preventing a single failing zone from derailing fleet-wide queries.
- Error format: Responses now use structured
google.rpc.ErrorInfoobjects with reason, domain, and metadata fields—making errors more programmatically parseable. - Permissions and schemas: Newer versions can tighten overly permissive legacy IAM checks and modernize aging resource definitions, all without affecting automation locked to /v1.

