Convenzione per l'intestazione della risposta HTTP per notificare ai client l'API deprecata

86

Sto aggiornando i nostri endpoint API REST e desidero avvisare i client quando chiamano l'endpoint da deprecare.
Quale intestazione devo usare nella risposta con un messaggio del tipo "Questa versione API è obsoleta, consulta la documentazione più recente per aggiornare i tuoi endpoint"

— BlazingFrog
fonte

75

Non cambierei nulla nel codice di stato per renderlo compatibile con le versioni precedenti. Aggiungerei un'intestazione "Avviso" nella risposta:

Warning: 299 - "Deprecated API"

Puoi anche specificare il "-" con l '"Agente" che emette l'avviso, ed essere più esplicito nel testo dell'avviso:

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

L'intestazione di avviso è specificata qui: https://tools.ietf.org/html/rfc7234#section-5.5 . Il codice di avviso 299 è generico, "Deprecato" non è standard.

Devi dire ai tuoi client API di registrare gli avvisi HTTP e monitorarli.

Non l'ho mai usato fino ad ora, ma quando la mia azienda sarà più matura in Rest API la integrerò.

Modifica (2019-04-25): come menzionato da @Harry Wood, l'intestazione di avviso si trova in un capitolo relativo alla memorizzazione nella cache nella documentazione. Tuttavia, la RFC è chiaraWarnings can be used for other purposes, both cache-related and otherwise.

Se preferisci un metodo alternativo, questa bozza https://tools.ietf.org/html/draft-dalal-deprecation-header-00 suggerisce una nuova intestazione "Deprecation".

— BenC
fonte

1

La data di avviso alla fine del valore di avviso non serve a niente qui, ed è meglio ometterla, o rischi di confondere i clienti: “Se un destinatario. . . riceve una data di avviso diversa dal Datevalore nello stesso messaggio, il destinatario DEVE escludere il valore di avviso. . . prima . . . utilizzando il messaggio. "

— Vasiliy Faronov

Se si includono la guardia-data, deve essere formattato allo stesso modo come Datel'intestazione: "Thu, 02 Apr 2015 12:25:32 GMT".

— Vasiliy Faronov

@VasiliyFaronov: hai ragione, perché in quel caso (API deprecata) questo messaggio di avviso sarà sempre vero in futuro. Quindi, se la risposta (con il messaggio di avviso) viene inviata da una cache in un proxy e che la data del messaggio è diversa, l'avviso verrà ignorato mentre sarà comunque valido. Modifico la risposta

— BenC

L'intestazione di "avviso" non è tuttavia correlata alla memorizzazione nella cache? Voglio dire che nel tuo link alla documentazione viene menzionato il caching, ma anche l'intero documento RFC sembra essere correlato al caching. Ma l' Warningintestazione sembra buona come posizione di testo libero per descrivere la deprecazione. Le intestazioni Deprecatione Sunsetmenzionate in altre risposte, sembrerebbero essere una soluzione standard emergente per descrivere la deprecazione in un modo più stretto e potenzialmente leggibile dalla macchina.

— Harry Wood

1

Warningl'intestazione non è correlata solo alle cache. La prima frase nella Warningsezione è "Gli avvisi possono essere utilizzati per altri scopi, sia relativi alla cache che di altro tipo."

— Çelebi Murat,

37

Potresti usare 410 (Gone) .

Ecco come lo descrivono le definizioni dei codici di stato del W3C :

410 (andato)

La risorsa richiesta non è più disponibile sul server e non è noto alcun indirizzo di inoltro. Questa condizione dovrebbe essere considerata permanente. I client con funzionalità di modifica dei collegamenti DOVREBBERO eliminare i riferimenti all'URI di richiesta dopo l'approvazione dell'utente. Se il server non sa o non ha la possibilità di determinare se la condizione è permanente o meno, DOVREBBE essere utilizzato il codice di stato 404 (Not Found). Questa risposta è memorizzabile nella cache se non diversamente indicato.

La risposta 410 è destinata principalmente ad assistere l'attività di manutenzione web notificando al destinatario che la risorsa è intenzionalmente non disponibile e che i proprietari del server desiderano che i collegamenti remoti a quella risorsa vengano rimossi. Un tale evento è comune per i servizi promozionali a tempo limitato e per le risorse appartenenti a persone che non lavorano più sul sito del server. Non è necessario contrassegnare tutte le risorse permanentemente non disponibili come "esaurite" o mantenere il segno per un certo periodo di tempo - ciò è lasciato alla discrezione del proprietario del server.

— Emanuil Rusev
fonte

36

Il problema con 410 è che non soddisfa il requisito "to-be-deprecated" ... Funziona bene quando l'API è andata, ma non che lo sarà in futuro .

— Julien Genestoux

3

Se restituisci 410 interromperai la compatibilità con le versioni precedenti

— BenC

4

410 Gonenon si tratta di deprecazione, si tratta di metodi non più disponibili. Come ha detto @BenC, il modo migliore è usare l' intestazione di avviso

— sempasha

2

Questa potrebbe essere la fase successiva dell'API deprecata

— Shiplu Mokaddim il

16

Sarei andato con 301 (spostato in modo permanente) I codici della serie 300 dovrebbero dire al cliente che hanno un'azione da fare.

— u07ch
fonte

4

Questo è probabilmente quello che userò una volta che l'endpoint è stato effettivamente rimosso, ma voglio dare loro la possibilità di ricevere una notifica per un po 'di tempo (supponendo che guarderanno le intestazioni HTTP nella risposta) in modo che possano apportare le modifiche necessarie su la loro fine.

— BlazingFrog

2

Non c'è davvero uno stato per andare a traslocare. 302 (La risorsa richiesta risiede temporaneamente in un'altra posizione, ma può ancora essere trovata nell'URI richiesto.) ...

— u07ch

1

Non cerco uno stato ma un'intestazione "standard" da aggiungere alla risposta.

— BlazingFrog

1

Non esiste un'intestazione standard per questo tipo di risposta. Dovresti creare una tua intestazione e descriverla nella documentazione della tua API.

— Brian Kelly

Penso che qualsiasi codice di risposta> = 300 dovrebbe rompere le cose. 299 consentirà ai client di mantenere attiva la propria applicazione finché l'API non viene disabilitata mentre apportano le modifiche necessarie.

— devlord

6

Consiglierei a 207 Multi-Status risposta, indicando che si tratta di una risposta positiva, ma potenzialmente ha anche un secondo stato deprecato.

— typeoneerror
fonte

1

Interessante. Non lo sapevo, ma penso che in pratica ci sia un forte pericolo che tu possa introdurre un cambiamento radicale per alcuni client passando a un codice di risposta diverso anche se è ancora nell'intervallo 200. Immagino che potresti aumentare delicatamente la pressione. Inizia con Deprecationun'intestazione (che è probabile che i client ignorino purtroppo), quindi utilizza questo codice 207 in seguito, quindi spostato 301, infine 410 andato!

— Harry Wood

4

Affinamento della risposta di @ dret. Esistono due intestazioni HTTP rilevanti per la deprecazione: Deprecation( https://tools.ietf.org/html/draft-dalal-deprecation-header-00 ) e Sunset.

Per informare gli utenti sul ritiro pianificato, è Deprecationnecessario utilizzare l'intestazione HTTP. Ciò indica che l'endpoint verrà eliminato per qualche tempo in futuro. Consente inoltre di indicare la data in cui è stato annunciato e di descrivere risorse alternative.

Per informare gli utenti sulla data di scadenza pianificata della risorsa deprecata, è Sunsetnecessario utilizzare l' intestazione in aggiunta all'intestazione di ritiro. Questo è descritto nella sezione # 5 https://tools.ietf.org/html/draft-dalal-deprecation-header-00#section-5 .

Progetto # 11 https://tools.ietf.org/html/draft-wilde-sunset-header-11 delle Sunsetchiarisce intestazione anche questo aspetto nella sezione 1.4 https://tools.ietf.org/html/draft-wilde -sunset-header-11 # sezione-1.4 .

— sdatspun2
fonte

3

È presente un campo di intestazione HTTP chiamato Sunsetche ha lo scopo di segnalare un'imminente deprecazione di una risorsa. https://tools.ietf.org/html/draft-wilde-sunset-header è nelle ultime fasi per diventare un RFC. Idealmente, la tua API dovrebbe documentare che verrà utilizzata Sunset, in modo che i clienti possano cercarla e agire di conseguenza, se lo desiderano.

— dret
fonte