Convention pour l'en-tête de réponse HTTP afin de notifier aux clients les API dépréciées

Question

Je suis en train de mettre à jour les points de terminaison de notre API REST et je veux avertir les clients lorsqu'ils appellent le point de terminaison qui va être déprécié.
Quel en-tête dois-je utiliser dans la réponse avec un message du type "Cette version de l'API est obsolète, veuillez consulter la dernière documentation pour mettre à jour vos points d'extrémité" ?

Answer 1

Je ne changerais rien au code d'état pour être compatible avec le passé. J'ajouterais un en-tête "Warning" dans la réponse :

Warning: 299 - "Deprecated API"

Vous pouvez également spécifier le "-" avec l'"Agent" qui émet l'avertissement, et être plus explicite dans le texte de l'avertissement :

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

L'en-tête d'avertissement est spécifié ici : https://www.rfc-editor.org/rfc/rfc7234#section-5.5 . Warn-code 299 est générique, "Déprécié" n'est pas standard.

Vous devez indiquer à vos clients API d'enregistrer les avertissements HTTP et de les surveiller.

Je ne l'ai jamais utilisé jusqu'à présent, mais lorsque mon entreprise sera plus mature en matière d'API Rest, je l'intégrerai.

Modifier (2019-04-25) : Comme @Harry Wood l'a mentionné, l'en-tête Warning se trouve dans un chapitre lié à la mise en cache dans la documentation. Cependant, la RFC est claire Warnings can be used for other purposes, both cache-related and otherwise.

Si vous préférez une autre méthode, cette ébauche https://datatracker.ietf.org/doc/html/draft-dalal-deprecation-header-00 propose un nouvel en-tête "Dépréciation".

Edit (2021-01-04) : Comme @Dima Parzhitsky l'a mentionné, MDN dit ceci est obsolète

Answer 2

Vous pourriez utiliser 410 (Disparu) .

Voici comment le W3C Définitions des codes d'état le décrire :

410 (Disparu)

La ressource demandée n'est plus disponible sur le serveur et aucune adresse de transfert n'est connue. et aucune adresse de réexpédition n'est connue. Cette condition est censée être considérée comme permanente. Les clients disposant de capacités d'édition de liens DEVRAIENT supprimer les références à l'URI de la demande après approbation de l'utilisateur. Si le serveur ne sait pas, ou ne dispose d'aucun moyen de déterminer, si la condition permanent, le code d'état 404 (non trouvé) DEVRAIT être utilisé à la place. être utilisé à la place. Cette réponse peut être mise en cache, sauf indication contraire.

La réponse 410 est principalement destinée à faciliter la tâche des utilisateurs du Web. web en informant le destinataire que la ressource est intentionnellement indisponible et que les propriétaires du serveur souhaitent que que les liens distants vers cette ressource soient supprimés. Un tel événement est courant pour services promotionnels à durée limitée et pour les ressources appartenant à des des personnes qui ne travaillent plus sur le site du serveur. Il n'est pas nécessaire de marquer toutes les ressources indisponibles de façon permanente comme "parties" ou ou de conserver cette marque pendant un certain temps -- cela est laissé à la discrétion du propriétaire du serveur.

Answer 3

Je serais/aurais été avec 301 (Moved Permanently) Les codes de la série 300 sont censés indiquer au client qu'il doit effectuer une action.

Answer 4

Affiner la réponse de @dret. Il existe deux en-têtes HTTP pertinents pour la dépréciation : Deprecation ( https://datatracker.ietf.org/doc/html/draft-dalal-deprecation-header-00 ) et Sunset .

Afin d'informer les utilisateurs de la dépréciation prévue, l'onglet Deprecation L'en-tête HTTP doit être utilisé. Ceci indique que le point de terminaison sera abandonné un certain temps à l'avenir. Il vous permet également d'indiquer la date à laquelle cela a été annoncé et de décrire les ressources alternatives.

Pour informer les utilisateurs de la date d'expiration prévue de la ressource dépréciée, l'outil de gestion de l'information de l'entreprise doit être utilisé. Sunset doit être utilisé en plus de l'en-tête Deprecation. Ceci est décrit dans la section 5 https://datatracker.ietf.org/doc/html/draft-dalal-deprecation-header-00#section-5 .

Projet n°11 https://datatracker.ietf.org/doc/html/draft-wilde-sunset-header-11 de la Sunset L'en-tête clarifie également cet aspect dans la section 1.4. https://datatracker.ietf.org/doc/html/draft-wilde-sunset-header-11#section-1.4 .

Answer 5

Je recommanderais un 207 Multi-Status qui indique qu'il s'agit d'une réponse réussie, mais qui peut aussi avoir un deuxième état déprécié.