API-Kompatibilitätsrichtlinie und Richtlinien für Nichtweiterverwendung

Kompatibilitätsrichtlinie

Kompatibilität mit früheren Versionen oder Non-Breaking Changes

Hinzufügen eines Ressourcen-URI, der unter Umständen eine vorhandene API-Ressource erweitert

Diese Änderung ist im Allgemeinen sicher. Bei der Änderung müssen jedoch gängige Client-Frameworks berücksichtigt werden, die möglicherweise Code generieren, der mit dieser Änderung in Konflikt steht. Die folgenden Beispiele sind Typen von Änderungen, die vermieden werden sollten, da sie möglicherweise vom Client generierten Code zerstören könnten.

• Eine API ist in /v1.0/foo/bar vorhanden. Der Codegenerator generiert möglicherweise GetBar als eine Clientmethode. /v1.0/foo/{param}Wenn eine neue API eingeführt wird, wobei {param} eine beliebige Zeichenfolge ist, generiert der Codegenerator die neue Client-Methode möglicherweise als GetFoo(String param). Diese Änderung kann auf dem Client einen Breaking Change zur Folge haben, da die in GetBar eingebettete Logik nicht mehr aufgerufen wird.
• Ein aktueller Pfad wie /v1.0/foo/bar kann den vom Client generierten Code GetBar und GetBarAsync zur Folge haben. Das Hinzufügen einer API /v1.0/foo/Async steht im Konflikt mit diesem generierten Code.

HTTP-Methode einer API-Schnittstelle hinzufügen

Diese Änderung ist unter der Bedingung sicher, dass die Anforderungsnutzdaten vor dieser Änderung weiterhin vorhanden sind und dasselbe Verhalten zeigen. Ein oder mehrere optionale Felder können dem Anforderungshauptteil einer vorhanden API oder als Abfragezeichenfolgeparameter hinzugefügt werden.

Optionale Anforderungsheader hinzufügen

Diese Änderung ist unter der Bedingung sicher, dass die Anforderung vor dieser Änderung weiterhin auf dieselbe Art und Weise antwortet.

Zulässigen Wert zu einer vorhandenen Eigenschaft hinzufügen

API-Modelle verwenden Zeichenfolgen, um Eigenschaften dazustellen, die eine eingeschränkte Liste mit Werten zulassen. Beispielsweise kann type in einer Ressource zum Auflisten der aktuellen Liste der Ressourcentypen dokumentiert werden. Vom Client wird erwartet, dass er statt der strikten Deserialisierung eines klar klar strukturierten Typs enum eine generische Zeichenfolge für diese Typen verwendet. Eine Ressource, die eine Eigenschaft mit mehreren möglichen Werten akzeptiert, kann erweitert werden, um mehr Werte zuzulassen. Dieser neue Wert oder diese neuen Werte können entsprechende neue Eigenschaften und Validierungsregeln einführen. Ein Client muss sicherstellen, dass er keine nicht vorhandenen enum-Werte validiert, indem er beispielsweise eine Anforderung mit einem ungültigen enum-Wert sendet und eine Fehlerantwort erwartet.

Vorhandene Eigenschaftswerte unterstützen weiterhin das vorhandene Verhalten. Jeder Client-Code, der beispielsweise Verzweigungslogik für den Ressourcentyp enthält, funktioniert weiterhin wie bisher.

Optionale Felder und/oder Header zu einer Antwort hinzufügen

Optionale Felder und Header können einer API-Antwort jederzeit hinzugefügt werden. Der Client Anpassungen für derartige Änderungen ausführen.

Fehlernachricht oder Ressourcenbeschreibungen in der API-Antwort ändern

Das Feld messageId in einer Fehlerantwort wird als nicht änderbar betrachtet und es wird davon ausgegangen, dass es immer die angegebene Liste der Fehlerbedingungen oder -situationen abdeckt. Die Beschreibung, die dieser Nachricht zugeordnet ist, kann sich ändern, ohne dass sich die semantische Bedeutung der Nachricht für einen Benutzer ändert.

Clients dürfen keine Logik auf der Basis des Attributs messageDescription erstellen.

Geltungsbereich einer Fehlernachrichten-ID vergrößern

Das Feld messageId bezieht sich auf eine oder mehrere Fehlerbedingungen. Diese Nachrichten-ID (messageId) kann jederzeit erweitert werden, um mehr Fehlerbedingungen gleichzeitig abzudecken. Es wird jedoch davon ausgegangen, dass jede derartige Erweiterung logisch und nicht willkürlich ist. Die neuen Fehlerbedingungen müssen in engem Zusammenhang mit einer vorhandenen Fehlerbedingung stehen, die von dieser Nachricht abgedeckt wird.

Ratenbegrenzungen für Header und Fehler

Die Ratenbegrenzungen können während der Lebensdauer der API in API-Endpunkten angepasst werden und erfordern keine Versionsaktualisierung.

Der Client, der den HTTP-Statuscode 429 für zu viele Anforderungen empfängt, muss Anpassungen ausführen.

Breaking Changes

API-Ressourcenendpunkt oder HTTP-Methode entfernen oder umbenennen

Dieser Typ von Änderung führt zum Fehlschlagen jedes Clients, der die API ohne Berechtigung verwendet, es sei denn, die Durchführung dieser Änderung ist aufgrund einer dringend erforderlichen Sicherheitsanforderung notwendig. Es wird alles unternommen, um eine derartige Änderung zu verhindern.

enum-Werte entfernen oder umbenennen

Werte für enum können hinzugefügt, aber nicht entfernt werden.

Typ (type) eines Felds ändern

Im Allgemeinen darf der Typ (type) eines Felds nicht geändert werden. Wenn die API-Implementierung den vorherigen Wert für type jedoch akzeptieren kann und mit dem vorherigen Wert für type antwortet, wird diese Änderung als mit früheren Versionen kompatibel betrachtet.

Sichtbares Verhalten vorhandener Anforderungen ändern

Wenn eine Anforderung zuvor eine bestimmte Aktion oder Antwort zur Folge hatte, muss sie weiterhin dasselbe Verhalten zeigen. Die einzige Ausnahme sind die Erweiterungen, die an einem vorhandenen Vertrag in Form neuer Fehlernachrichten, HTTP-Statuscodes und Anforderungs- oder Antwortfelder zulässig sind.

Richtlinie für die Nichtweiterverwendung