Konvention für HTTP-Antwortheader zum Benachrichtigen von Clients über veraltete API

84

Ich aktualisiere unsere REST-API-Endpunkte und möchte Clients benachrichtigen, wenn sie den zu veraltenden Endpunkt aufrufen.
Welchen Header sollte ich in der Antwort mit der Meldung "Diese API-Version ist veraltet, konsultieren Sie die neueste Dokumentation, um Ihre Endpunkte zu aktualisieren" verwenden.

rest http http-status-codes deprecation-warning BlazingFrog
quelle

Antworten:

72

Ich würde nichts am Statuscode ändern, um abwärtskompatibel zu sein. Ich würde der Antwort einen "Warning" -Header hinzufügen:

Warning: 299 - "Deprecated API"

Sie können das "-" auch mit dem "Agenten" angeben, der die Warnung ausgibt, und im Warnungstext expliziter sein:

Warning: 299 api.blazingFrog.com "Deprecated API: use betterapi.blazingFrog.com instead. Old API maintained until 2015-06-02"

Der Warnheader wird hier angegeben: https://tools.ietf.org/html/rfc7234#section-5.5 . Der Warncode 299 ist generisch, "Veraltet" ist kein Standard.

Sie müssen Ihre API-Clients anweisen, die HTTP-Warnungen zu protokollieren und zu überwachen.

Ich habe es bis jetzt noch nie verwendet, aber wenn mein Unternehmen in der Rest-API reifer wird, werde ich es integrieren.

Bearbeiten (25.04.2019): Wie @Harry Wood erwähnt hat, befindet sich der Warning-Header in einem Kapitel zum Caching in der Dokumentation. Der RFC ist jedoch klarWarnings can be used for other purposes, both cache-related and otherwise.

Wenn Sie eine alternative Methode bevorzugen, schlägt dieser Entwurf https://tools.ietf.org/html/draft-dalal-deprecation-header-00 einen neuen Header "Deprecation" vor.

BenC
quelle
1
Das Warndatum am Ende des Warnwerts hat hier keinen Zweck, und es ist am besten, es wegzulassen, oder Sie riskieren, Kunden zu verwirren: „Wenn ein Empfänger. . . Empfängt ein Warndatum, das sich vom DateWert in derselben Nachricht unterscheidet, MUSS der Empfänger den Warnwert ausschließen. . . Vor . . . mit der Nachricht. "
Vasiliy Faronov
Wenn Sie das Warndatum angeben, muss es wie der DateHeader formatiert werden : "Thu, 02 Apr 2015 12:25:32 GMT".
Vasiliy Faronov
@VasiliyFaronov: Sie haben Recht, denn in diesem Fall (veraltete API) wird diese Warnmeldung in Zukunft immer wahr sein. Wenn also die Antwort (mit der Warnmeldung) von einem Cache in einem Proxy gesendet wird und das Nachrichtendatum unterschiedlich ist, wird die Warnung ignoriert, solange sie noch gültig ist. Ich bearbeite die Antwort
BenC
Bezieht sich dieser "Warn" -Header nicht auf das Caching? Ich meine, in Ihrem Dokumentationslink wird das Caching erwähnt, aber auch das gesamte RFC-Dokument scheint mit dem Caching in Zusammenhang zu stehen. Die WarningKopfzeile sieht jedoch als Freitextstelle zur Beschreibung der Ablehnung gut aus. Die Deprecationund SunsetHeader in anderen Antworten erwähnten, scheinen eine aufstrebende Standardlösung für die Beschreibung der deprecation in einer festeren potenziell maschinenlesbaren Art und Weise zu sein.
Harry Wood
1
WarningDer Header bezieht sich nicht nur auf Caches. Der erste Satz im WarningAbschnitt lautet "Warnungen können für andere Zwecke verwendet werden, sowohl im Zusammenhang mit dem Cache als auch auf andere Weise."
Çelebi Murat
37

Sie könnten 410 (Gone) verwenden .

So beschreiben es die Statuscode-Definitionen von W3C :

410 (weg)

Die angeforderte Ressource ist auf dem Server nicht mehr verfügbar und es ist keine Weiterleitungsadresse bekannt. Es wird erwartet, dass dieser Zustand als dauerhaft angesehen wird. Clients mit Linkbearbeitungsfunktionen MÜSSEN nach Genehmigung durch den Benutzer Verweise auf den Anforderungs-URI löschen. Wenn der Server nicht weiß oder nicht feststellen kann, ob die Bedingung dauerhaft ist oder nicht, sollte stattdessen der Statuscode 404 (Nicht gefunden) verwendet werden. Diese Antwort kann zwischengespeichert werden, sofern nicht anders angegeben.

Die 410-Antwort soll in erster Linie die Aufgabe der Webwartung unterstützen, indem der Empfänger benachrichtigt wird, dass die Ressource absichtlich nicht verfügbar ist und die Serverbesitzer wünschen, dass Remoteverbindungen zu dieser Ressource entfernt werden. Ein solches Ereignis ist häufig für zeitlich begrenzte Werbedienste und für Ressourcen von Personen, die nicht mehr am Standort des Servers arbeiten. Es ist nicht erforderlich, alle permanent nicht verfügbaren Ressourcen als "weg" zu markieren oder die Markierung für einen beliebigen Zeitraum beizubehalten - dies liegt im Ermessen des Serverbesitzers.

Emanuil Rusev
quelle
35
Das Problem mit 410 ist, dass es nicht der Anforderung "zu veralten" entspricht ... Es funktioniert gut, wenn die API weg ist, aber nicht, dass es in Zukunft weg sein wird .
Julien Genestoux
3
Wenn Sie 410 zurückgeben, brechen Sie Ihre Abwärtskompatibilität
BenC
4
410 GoneEs geht nicht um Abwertung, es geht viel um nicht mehr verfügbare Methoden. Wie @BenC sagte, ist der bessere Weg, Warning Header
Sempasha
2
Dies könnte die nächste Phase der veralteten API sein
Shiplu Mokaddim
16

Ich wäre / wäre mit 301 gegangen (dauerhaft verschoben). Die Codes der 300er-Serie sollen dem Kunden mitteilen, dass sie eine Aktion ausführen müssen.

u07ch
quelle
4
Das werde ich wahrscheinlich verwenden, sobald der Endpunkt tatsächlich entfernt wurde, aber ich möchte ihnen die Möglichkeit geben, für einige Zeit benachrichtigt zu werden (vorausgesetzt, sie sehen sich die HTTP-Header in der Antwort an), damit sie die erforderlichen Änderungen vornehmen können ihr Ende.
BlazingFrog
2
Es gibt nicht wirklich einen Status für den Umzug. 302 (Die angeforderte Ressource befindet sich vorübergehend an einem anderen Speicherort, kann jedoch weiterhin an der angeforderten URI gefunden werden.) ...
u07ch
1
Ich suche nicht nach einem Status, sondern nach einem "Standard" -Header, der der Antwort hinzugefügt werden kann.
BlazingFrog
1
Es gibt keinen Standardheader für diese Art von Antwort. Sie sollten einen eigenen Header erstellen und diesen in der Dokumentation Ihrer eigenen API beschreiben.
Brian Kelly
Ich denke, jeder Antwortcode> = 300 soll die Dinge kaputt machen. Mit 299 können Clients ihre Anwendung so lange am Leben erhalten, bis die API deaktiviert ist, während sie die erforderlichen Änderungen vornehmen.
Devlord
6

Ich würde eine 207 Multi-StatusAntwort empfehlen , die angibt, dass es sich um eine erfolgreiche Antwort handelt, aber möglicherweise auch einen zweiten veralteten Status hat.

typoneerror
quelle
1
Interessant. Ich wusste nichts davon, aber ich denke, in der Praxis besteht die große Gefahr, dass Sie für einige Kunden eine bahnbrechende Änderung einführen, indem Sie zu einem anderen Antwortcode wechseln, selbst wenn dieser noch im Bereich von 200 liegt. Ich denke, Sie könnten eine Art sanften Druckanstieg machen. Beginnen Sie mit einem DeprecationHeader (den Clients wahrscheinlich leider ignorieren) und verwenden Sie später diesen 207-Code, dann später 301 verschoben, dann endlich 410 weg!
Harry Wood
4

Verfeinerung der Antwort von @ dret. Es gibt zwei relevante HTTP-Header für die Ablehnung: Deprecation( https://tools.ietf.org/html/draft-dalal-deprecation-header-00 ) und Sunset.

Um Benutzer über die geplante Ablehnung zu informieren, sollte der DeprecationHTTP-Header verwendet werden. Dies zeigt an, dass der Endpunkt wird fallen gelassen werden einige Zeit in der Zukunft. Außerdem können Sie das Datum angeben, an dem dies angekündigt wurde, und alternative Ressourcen beschreiben.

Um Benutzer über das geplante Verfallsdatum der veralteten Ressource zu informieren, sollte der SunsetHeader zusätzlich zum Header "Veraltet" verwendet werden. Dies wird in Abschnitt 5 https://tools.ietf.org/html/draft-dalal-deprecation-header-00#section-5 beschrieben .

Der Entwurf Nr. 11 https://tools.ietf.org/html/draft-wilde-sunset-header-11 des SunsetHeaders verdeutlicht diesen Aspekt auch in Abschnitt 1.4 https://tools.ietf.org/html/draft-wilde -sunset-header-11 # section-1.4 .

sdatspun2
quelle
3

Es wird ein HTTP-Headerfeld aufgerufen, Sunsetdas eine bevorstehende Abwertung einer Ressource signalisieren soll. https://tools.ietf.org/html/draft-wilde-sunset-header befindet sich in den letzten Phasen der RFC-Entwicklung. Im Idealfall sollte Ihre API dokumentieren, dass sie verwendet wird Sunset, damit Clients danach suchen und darauf reagieren können, wenn sie dies möchten.

dret
quelle