Kompatibilität

Was wir an v1 ohne Ankündigung ändern dürfen und was eine neue Hauptversion erfordern würde. Als aufgezählte Liste formuliert statt als Versprechen, damit eine Integration defensiv gegen genau die richtige Menge gebaut werden kann.

Pfade, Methoden, Scopes, Feldnamen und Fehlercodes erscheinen auf Englisch, denn Englisch ist die Sprache der Schnittstelle selbst — es ist das, was ein Aufrufer eintippt oder abgleicht. Ebenso jedes Codebeispiel, jede JSON-Nutzlast und der exakte Satz, den eine Fehlerantwort mitführt: /v1 wertet Accept-Language nicht aus, und eine Übersetzung dessen, was die API tatsächlich sendet, würde sie falsch beschreiben. Alles, was darüber geschrieben steht, folgt der Sprache dieser Seite.

Die aktuelle Revision ist 2026-08-01. Der Pfad bleibt /v1; die Revision benennt das Dokument, das ihn beschreibt.

Änderungen, die wir an v1 nicht vornehmen

Diese erfordern eine neue Hauptversion. Sollten wir je eine brauchen, antworten bestehende Versionen während der Umstellung weiter.

Eine Operation entfernen.
Einen Parameter oder ein Feld einer Antwort entfernen oder umbenennen.
Einen neuen Pflichtparameter einführen.
Einen bisher optionalen Parameter zum Pflichtparameter machen.
Den Typ eines Parameters oder eines Antwortfelds ändern.
Einen Wert aus einer Aufzählung entfernen.Ein Client, der auf den Wert verzweigt, hat für dessen Ausbleiben keinen Zweig und scheitert daher so, wie seine Sprache bei einem unbehandelten Fall eben scheitert.
Eine neue Validierungsregel für einen bestehenden Parameter einführen.Eine Anfrage, die gestern noch durchging, würde plötzlich scheitern — der Entzug einer Fähigkeit im Kostüm einer Fehlerbehebung.
Die Anforderungen an Authentifizierung oder Autorisierung ändern, einschließlich des Scopes, den eine Operation verlangt.

Änderungen, die wir jederzeit vornehmen dürfen

Ihre Integration muss all das vertragen. Es wird eintreten, und es wird nicht angekündigt.

Eine neue Operation hinzufügen.
Einen neuen optionalen Parameter hinzufügen.
Einen neuen optionalen Anfrage-Header hinzufügen.
Ein neues Feld zu einer Antwort hinzufügen.Werten Sie Antworten großzügig aus — ein Client, der unbekannte Felder ablehnt, bricht schon bei unserer ersten Ergänzung.
Einen neuen Antwort-Header hinzufügen.
Einen Wert zu einer Aufzählung hinzufügen.Behandeln Sie einen unbekannten Wert als Standardfall und nicht als Fehler. Neue Produktpass-Kategorien und neue Ereignistypen werden hinzukommen.
Einen Fehlercode in genauere Codes aufteilen — aber nur dort, wo der ursprüngliche Code sich nicht durch Laufzeitlogik wie einen erneuten Versuch auflösen ließ.Einen Code aufzuteilen, auf den ein Client VERZWEIGT, ist ein Bruch; einen, den er nur protokolliert, nicht. Entscheidend ist, ob Verhalten davon abhing.

Was Ihr Client vertragen muss

Jeder dieser Punkte entspricht einer Änderung oben, die wir uns vorbehalten. Ein Client, der einen davon verletzt, bricht an etwas, das wir für Routine halten.

Ignorieren Sie Antwortfelder, die Sie nicht kennen, statt die Antwort abzulehnen.
Behandeln Sie einen unbekannten Aufzählungswert als Standardfall, nicht als Fehler.
Behandeln Sie Kennungen als opake Zeichenketten; zerlegen Sie sie nie und gleichen Sie sie nie gegen Muster ab.
Verlassen Sie sich nicht auf die REIHENFOLGE der Felder in einem JSON-Objekt und nicht auf den genauen Wortlaut einer für Menschen gedachten Fehlermeldung. Verzweigen Sie stattdessen auf den maschinenlesbaren Fehlercode.
Wiederholen Sie bei 429 und bei jeder anderen Ablehnung, die einen Retry-After-Header führt, und warten Sie die dort genannte Zeit ab. Der Header gehört nicht nur zum 429: Auch ein 409 resource_busy, ein 503 storage_unavailable und ein 503 entitlement_unavailable führen ihn, weil ein erneuter Versuch dort die Abhilfe ist.
Wiederholen Sie eine 5xx mit einem NEUEN Idempotency-Key. Ein Schlüssel, der einen Serverfehler festgehalten hat, spielt diesen Fehler für die gesamte Aufbewahrungsfrist erneut ab — mit Absicht, denn der Fehlschlag kann eine verlorene Antwort auf einen Schreibvorgang gewesen sein, der GELUNGEN ist, und genau die Wiederverwendung des Schlüssels verhindert, dass aus einem fehlgeschlagenen Schreibvorgang zwei werden.
Achten Sie auf die Antwort-Header Deprecation und Sunset sowie auf den Link: rel="successor-version", den sie mitführen. So wird die Entfernung eines Endpunkts angekündigt, und sie trifft lange ein, bevor der Endpunkt aufhört zu antworten.

Behandeln Sie jede Kennung als opake Zeichenkette von höchstens 255 Zeichen. Zerlegen Sie sie nicht, prüfen Sie ihr Format nicht und gehen Sie nicht davon aus, dass es UUIDs sind — das Format kann sich ohne Ankündigung ändern.

Abkündigung

Ein zur Entfernung vorgesehener Endpunkt antwortet mit Deprecation- und Sunset-Headern sowie einem Link-Header, der den Nachfolger benennt. Sie treffen lange ein, bevor der Endpunkt aufhört zu antworten. Achten Sie darauf.