Lebenszyklus

Die API basiert auf einem einzigen, sich weiterentwickelnden GraphQL-Endpoint. Diese Architektur stellt sicher, dass neue Funktionen und Leistungsverbesserungen kontinuierlich bereitgestellt werden, ohne dass eine Migration zwischen API-Versionen erforderlich ist.

Diese Seite beschreibt die verschiedenen Stabilitätsstufen der API, die Stabilitätsgarantien der stabilen API, die Arten von Änderungen (breaking vs. nicht-breaking) und wie Verwerfungen gehandhabt werden. Informationen zu Funktionen, die sich derzeit in der Vorschau befinden, finden Sie unter experimentelle Funktionen.

Funktions-Lebenszyklus

Jede Funktion befindet sich auf einer von drei Stabilitätsstufen: Alpha, Beta oder Stabil. Die meisten Funktionen durchlaufen diese der Reihe nach, und stabile Funktionen können nur über einen Verwerfungsprozess eingestellt werden.

[ ALPHA ] ──> [ BETA ] ──> [ STABLE ] ──> [ DEPRECATED ] ──> [ REMOVED ] Opt-in        Enabled                      12+ month               by default                   notice window

Stabile API

Stabile Funktionen bilden den produktionsreifen Kern der API. Änderungen werden in zwei Kategorien eingeteilt: nicht-breaking und breaking.

Nicht-breaking Änderungen

Abwärtskompatible Ergänzungen, die bestehende Integrationen nicht beeinträchtigen. Diese werden kontinuierlich und ohne Vorankündigung oder Verwerfung veröffentlicht.

Zu den nicht-breaking Änderungen gehören:

• Hinzufügen einer neuen Query, Mutation oder Subscription.
• Hinzufügen eines neuen optionalen Eingabearguments zu einer bestehenden Operation.
• Hinzufügen eines neuen Arguments mit einem Standardwert, der das bestehende Verhalten beibehält.
• Hinzufügen eines neuen Felds zur Ausgabe einer bestehenden Operation.
• Ändern eines erforderlichen Eingabearguments in ein optionales.
• Hinzufügen eines neuen Werts zu einem bestehenden Enum-Typ.

Auf nicht-breaking Änderungen vorbereiten

Auch nicht-breaking Änderungen können Clients beeinträchtigen, die starre Annahmen treffen. So halten Sie Integrationen robust:

• Vermeiden Sie strikte Objekt-Deserialisierung, die fehlschlägt, wenn in Payloads zusätzliche Eigenschaften auftauchen.
• GraphQL-enum-Typen sind nicht abschließend und wachsen mit der Zeit. Implementieren Sie in der Client-Logik immer einen Fallback-Standardfall.
• Prüfen Sie die Werte von extensions.exception.code in Fehlern, anstatt gegen für Menschen lesbare Fehlerstrings abzugleichen.

Breaking Änderungen und Verwerfungen

Eine breaking Änderung kann aktive bestehende Integrationen beeinträchtigen. Deshalb muss jede breaking Änderung zuerst einen 12-monatigen Verwerfungsprozess durchlaufen.

Zu den breaking Änderungen gehören:

• Entfernen oder Umbenennen einer bestehenden Query, Mutation, Subscription, eines Felds oder Eingabearguments.
• Entfernen oder Umbenennen von Enum-Werten.
• Ändern des Datentyps eines bestehenden Felds oder Eingabearguments.
• Hinzufügen eines neuen erforderlichen Eingabearguments.
• Ändern eines optionalen Eingabearguments in ein erforderliches.
• Ändern der Geschäftslogik oder des Verhaltens eines bestehenden Felds.
• Ändern eines Ausgabefelds von nicht nullable (!) zu nullable.
• Ändern des Standardwerts eines Eingabearguments oder Felds.
• Ändern von Pagination-Standardwerten, maximalen Seitengrößen oder der dokumentierten Sortierreihenfolge.

Verwerfungszeitplan

Wenn eine breaking Änderung das Entfernen oder Ersetzen einer stabilen Funktion erfordert, folgt sie einem strikten Zeitplan in drei Phasen:

1. VerwerfungsankündigungDie Funktion wird im GraphQL-Schema mit der Direktive @deprecated gekennzeichnet. Falls zutreffend, wird ein Migrationspfad bereitgestellt. Die Verwerfung und das jeweilige Entfernungsdatum werden gleichzeitig über drei Überwachungskanäle angekündigt.
2. Aktive Ankündigungsfrist (Monate 1–12)Die verworfene Funktion bleibt voll funktionsfähig. Wenn ein Migrationspfad bereitgestellt wird, sollten Integratoren ihre Anwendungen in diesem 12-Monats-Zeitraum aktualisieren und die neuen Felder übernehmen.
3. Endgültiges EntfernenZum Entfernungsdatum wird die Funktion endgültig entfernt. Alle nachfolgenden Anfragen, die die Funktion verwenden, schlagen bei der Schemavalidierung mit einem GraphQL-Fehler fehl.

Verwerfungen nachverfolgen

Erkennen und verfolgen Sie bevorstehende Einstellungen über drei Kanäle:

• Prüfen Sie @deprecated(reason: "...")-Direktiven in Ihren Schema-Tools.
• Sehen Sie sich Sunset-Daten und Migrationsleitfäden im Legacy-Bereich der API oder im Verwerfungsportal an.
• Überwachen Sie DEPRECATED_FEATURE-Warnungen, die direkt in API-Antworten zurückgegeben werden.

{  "data": {    "station": {      "id": "5e8c22366f9c5f23ab0eff39",      "amenityList": [        {          "name": "Coffee Shop",          "foursquareUrl": "https://foursquare.com/v/example"        }      ]    }  },  "extensions": {    "warnings": [      {        "code": "DEPRECATED_FEATURE",        "path": ["amenityList", "foursquareUrl"],        "message": "This feature is deprecated and will be removed. To prevent errors and service disruptions, migrate to the recommended alternative before the scheduled removal date. Visit https://developers.chargetrip.com/deprecations for more information."      }    ]  }}