Was ist der richtige HTTP-Statuscode für: "Diese Version dieser API wurde eingestellt"?

Ich habe eine RESTful API. Es gibt 3 Versionen davon: v1, v2 und v3. Ich bin im Begriff, Version 4 zu veröffentlichen, und wir haben beschlossen, Version 1 einzustellen, was bedeutet, dass alle Anfragen nach http://example.com/v1/resourcefehlschlagen, Anrufe nach http://example.com/v2/resourcejedoch weiterhin funktionieren.

Was ist der geeignete Weg, um ein Versagen anzuzeigen? Ich habe überlegt, einen 410 GONEStatuscode zu verwenden, aber das zeigt an, dass die Ressource nicht mehr verfügbar ist. Die Ressource ist wahrscheinlich noch verfügbar, sie muss jedoch auf andere Weise angefordert werden.

Ich habe auch einen generischen 400Statuscode in Betracht gezogen , aber auch das schien seltsam. Gibt es eine Standardantwort dafür?

Es scheint keinen Standard zu geben.

Die StackOverflow- Antwort tendiert zu 410 GONE, aber ich denke, 301 MOVED PERMANENTLY ist angemessener.

Um die richtige Wahl zu treffen, müssen wir uns Ihren speziellen Fall ansehen. Wenn Ihr Ziel ist, dass alle Aufrufe an API v1 fehlschlagen, ohne dass weitere Maßnahmen ergriffen werden, funktioniert 410 GONE dafür. Wenn Sie eine gewisse Kontinuität wünschen, z. B. das Umleiten des Clients auf eine neuere Version Ihrer API, bei der der Aufruf möglicherweise erfolgreich ist, funktioniert 3XX. Aber welche wählen Sie aus? Ich denke, wenn Sie versuchen, API v1 herunterzufahren, hilft 301 MOVMANENTLY, anzuzeigen, dass besser als 303 SEE OTHER ist, da 301 vorschlägt, dass alle zukünftigen Anforderungen an die neue URL gesendet werden sollten, während 303 nicht angibt, ob dies der Fall ist oder nicht permanent.

Ich würde empfehlen, die API so zu entwickeln, dass jede Version abwärtskompatibel bleibt, damit 301 MOVED PERMANENTLY Ihre API transparent am Leben erhält und auf dem neuesten Stand bleibt, wenn Sie neue Endpunkte für neue API-Versionen hinzufügen. Ich denke, das ist es, was Sie sowieso versuchen.

HTTP-Statuscodes

Der HTTP-Statuscode 302 war ursprünglich zu weit gefasst und wurde daher falsch implementiert / verwendet. Daher wurden 303 und 307 erstellt, um zwischen dem doppelten Verwendungszweck von 302 zu unterscheiden. Einige APIs verwenden 303 für andere Zwecke.

301 Permanent verschoben - Der Statuscode 301 (Permanent verschoben) gibt an, dass der Zielressource ein neuer permanenter URI zugewiesen wurde und zukünftige Verweise auf diese Ressource einen der beigefügten URIs verwenden sollten.

302 GEFUNDEN - Der Statuscode 302 (Gefunden) gibt an, dass sich die Zielressource vorübergehend unter einem anderen URI befindet. Da die Umleitung gelegentlich geändert werden kann, sollte der Client die effektive Anforderungs-URI für zukünftige Anforderungen weiterhin verwenden.

303 SIEHE ANDERE - Eine 303 Antwort auf eine GET-Anforderung zeigt an, dass der Ursprungsserver keine Darstellung der Zielressource hat, die vom Server über HTTP übertragen werden kann. Der Wert im Feld "Standort" bezieht sich jedoch auf eine Ressource, die die Zielressource beschreibt, sodass eine Abrufanforderung für diese andere Ressource möglicherweise zu einer Darstellung führt, die für die Empfänger nützlich ist, ohne zu implizieren, dass sie die ursprüngliche Zielressource darstellt.

410 GONE - Der Statuscode 410 (Gone) gibt an, dass der Zugriff auf die Zielressource auf dem Ursprungsserver nicht mehr verfügbar ist und dass dieser Zustand wahrscheinlich dauerhaft ist. Wenn der Ursprungsserver nicht weiß oder nicht feststellen kann, ob die Bedingung dauerhaft ist oder nicht, sollte stattdessen der Statuscode 404 (Not Found) verwendet werden.

Wie gehen vorhandene APIs damit um?

Vielleicht können Sie eine Seite aus Googles Youtube-API entnehmen :

Wenn eine API-Anfrage fehlschlägt, gibt YouTube einen HTTP 4xx- oder 5xx-Antwortcode zurück, der den Fehler generisch identifiziert, sowie eine XML-Antwort, die spezifischere Informationen zu den Fehlern enthält, die den Fehler verursacht haben. Für jeden Fehler enthält die XML-Antwort ein Domänenelement, ein Codeelement und möglicherweise ein Standortelement.

• Die BigCommerce-API verwendet 302 FOUND.
• In den Richtlinien für Atlassian-REST-APIs wird auf 301 MOVED PERMANENTLY zusammen mit einem Untercode verwiesen, der den Fehler ausführlich beschreibt. Dies ähnelt dem Youtube-API-Ansatz.

Weitere Lektüre:

• Wie werden REST-APIs versioniert?
• Netflix-API-Design: Wann man sich gegen den Trend wehren sollte

Weiterleitungen eignen sich hervorragend für Ressourcen, die verschoben wurden. Anstelle einer permanenten 301-Umleitung (die eine Umbenennung ohne API-Änderungen anzeigt) würde ich eine 303-Umleitung "Andere anzeigen" verwenden.

Müssen Sie noch Legacy ohne Weiterleitungen unterstützen? Auch wenn Sie es immer noch unterstützen und es noch tiefgreifend implementiert ist, scheint das 501 eher Hand in Hand mit Ihrer Situation zu sein. Diejenigen, die Bescheid wissen, könnten es noch gebrauchen, während Zufällige die 501 für v1 sehen würden.

10.5.2 501 Nicht implementiert

Der Server unterstützt nicht die Funktionen, die zur Erfüllung der Anforderung erforderlich sind. Dies ist die geeignete Antwort, wenn der Server die Anforderungsmethode nicht erkennt und sie für keine Ressource unterstützen kann.

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Ich würde 503 mit einer Meldung verwenden, dass der Dienst nicht verfügbar ist, und angeben, die neuere Version zu verwenden. Diese Nachricht kann für 50% der Anrufe zurückgegeben werden und wird mit der Zeit schrittweise auf 100% erhöht.

Für eine transparente Migration würde ich 308 - Permanent Redirect verwenden, da diese Methode im Gegensatz zu 301 das Verb nicht ändert (POST wird POST sein).