Google Compute Engine ergänzt /v1 um datierte API-Versionen mit neuen Standardwerten
Google Cloud hat die Mehrfachversionierung der Compute-Engine-API allgemein verfügbar gemacht, berichtete InfoQ am 14. November. Neben der langlebigen Oberfläche /v1 können Aufrufer jetzt unveränderliche Versionen wählen, die nach einem Datum benannt sind. Stabile Versionen folgen dem Muster YYYY-MM-DD und erscheinen quartalsweise, beginnend mit 2026-09-01; Vorschauversionen tragen den Zusatz -preview und gelten ein Jahr.
Gewählt wird eine Version über den Header X-Goog-Api-Version oder den Abfrageparameter $apiVersion, auf demselben Pfad /compute/v1/ wie bisher. Eine Anfrage ohne Version bekommt weiterhin /v1, das kein Ablaufdatum hat. Jede stabile Version ist ein eingefrorener Stand aller allgemein verfügbaren Funktionen und Standardwerte zu ihrem Datum, und Google sagt, nach der Veröffentlichung werde nichts daran brechend geändert. Das Schema folgt Googles API Improvement Proposal AIP-185.
Der Grund ist laut einem Google-Blogbeitrag des Softwareingenieurs Michael Murstein, den InfoQ zitiert, dass /v1 eine einzige veränderliche Produktionsoberfläche für alle Kunden war. Schon die Korrektur eines unlogischen Standardwerts oder ein modernes Fehlerformat riskierte, Skripte zu brechen, oder brauchte eine jahrelange Migration.
Der Beitrag nennt drei Unterschiede in den neuen Versionen. AggregatedList liefert standardmäßig Teilergebnisse, während /v1 das nur mit gesetztem returnPartialSuccess tut; eine ausgefallene Zone lässt also keine flottenweite Abfrage mehr scheitern. Fehler werden zu strukturierten google.rpc.ErrorInfo-Objekten mit Grund, Domäne und Metadaten, und wer eine nicht existierende Version anfragt, bekommt die Liste der vorhandenen. Und neue Versionen erlauben es Compute Engine, zu weit gefasste alte IAM-Prüfungen zu verschärfen und alte Ressourcenschemata an die AIPs anzupassen, während an /v1 gebundene Automatisierung davon nichts merkt.
Die meisten Nutzer begegnen der Änderung über Werkzeuge. Client-Bibliotheken für Python, Go, Java, Node.js, C#, Ruby und PHP binden jedes Release an eine datierte Version und behalten die Namensräume compute_v1 und apiv1, Importpfade ändern sich also nicht. gcloud compute nutzt die gebündelte stabile Version, eine neue Gruppe gcloud preview compute die Vorschau. Der Terraform-Provider google nutzt stabile Versionen, google-beta die Vorschau, ohne Versionsangabe in HCL. Discovery-Dokumente erscheinen pro Version.

Warum es wichtig ist
Ein Update der Client-Bibliothek ändert jetzt das Verhalten der API, nicht nur den Code. Wer die Python- oder Go-Bibliothek anhebt, bekommt Teilergebnisse und strengere IAM-Prüfungen mit. Das ist gut für die Korrektheit, sollte aber getestet werden, denn eine flottenweite Abfrage, die früher laut scheiterte, gelingt nun mit fehlenden Zonen.