Google Cloud Introduces Date-Stamped API Versioning for Compute Engine

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. [1]

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. [1]

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 (InfoQ, 2026). Stable versions are named using YYYY-MM-DD format and are released quarterly, starting with 2026-09-01. Preview versions include a -preview suffix and have a one-year lifespan. A caller can select a version using the X-Goog-Api-Version header or the $apiVersion query parameter on the unchanged /compute/v1/ path. If no version is specified, the request defaults to /v1, which has no end-of-life date. [1]

Software engineer Michael Murstein explains that the problem with the existing /v1 API was its mutable nature, which made it challenging to introduce behavioral improvements without risking breaking changes for existing users. Google's new approach, called interface-based versioning, aligns with AIP-185, requiring stable versions to be date-stamped and previews to be time-bound. Each stable version is a locked snapshot of all generally available features and defaults at the time of release, with no breaking changes made after publication. [1]

The blog post highlights three key differences for API callers: the default behavior of the AggregatedList operation, which now returns partial results by default in date-based versions, unlike /v1. Error bodies are now structured as google.rpc.ErrorInfo with reason, domain, and metadata, and a request for a non-existent version lists available versions in the metadata. Additionally, new versions allow Compute Engine to refine legacy IAM permission checks and introduce safer configuration defaults, while automation pinned to /v1 remains unaffected. [1]

Sources

InfoQ

Prepared with AI assistance from the cited sources.