Convention pour l'en-tête de réponse HTTP pour informer les clients de l'API obsolète
Je mets à niveau nos points de terminaison API REST et je souhaite informer les clients lorsqu'ils appellent le point de terminaison à déprécier.
Quel en-tête dois-je utiliser dans la réponse avec un message du type "Cette version d'API est obsolète, veuillez consulter la dernière documentation pour mettre à jour vos points de terminaison"
Je ne changerais rien dans le code d'état pour être rétrocompatible. 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 d'avertissement:
Warning: 299 api.blazingFrog.com "Deprecated API : use betterapi.blazingFrog.com instead. Old API maintained until 2015-06-02"
Les en-têtes d'avertissement sont spécifiés ici: https://tools.ietf.org/html/rfc7234#section-5.5 . Le code d'avertissement 299 est générique, "Obsolète" n'est pas standard.
Vous devez dire à vos clients API de consigner les avertissements HTTP et de les surveiller.
Je ne l'ai jamais utilisé jusqu'à présent, mais lorsque mon entreprise sera plus mature dans l'API Rest, je l'intégrerai.
Edit (2019-04-25): Comme l'a mentionné @Harry Wood, l'en-tête Warning se trouve dans un chapitre relatif à la mise en cache dans la documentation. La RFC n'est pas claire car il est écrit qu'avec le code d'avertissement 199
The warning text can include arbitrary information to be presented to a human user or logged.Ce projet https://tools.ietf.org/html/draft-dalal-deprecation-header- propose un nouvel en-tête "Deprecation" qui peut devenir une bonne alternative.
Vous pouvez utiliser 410 (disparu) .
Voici comment le W3C Définitions des codes d'état le décrit:
410 (disparu)
La ressource demandée n'est plus disponible sur le serveur et aucune adresse de transfert n'est connue. Cette condition devrait être considérée comme permanente. Les clients dotés de capacités d'édition de lien DEVRAIENT supprimer les références à l'URI de demande après l'approbation de l'utilisateur. Si le serveur ne sait pas ou n'a pas la possibilité de déterminer si la condition est permanente ou non, le code d'état 404 (Not Found) DEVRAIT ê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 de maintenance Web en informant le destinataire que la ressource est intentionnellement indisponible et que les propriétaires de serveur souhaitent que les liens distants vers cette ressource soient supprimés. Un tel événement est courant pour les services promotionnels à durée limitée et pour les ressources appartenant à des personnes ne travaillant plus sur le site du serveur. Il n'est pas nécessaire de marquer toutes les ressources indisponibles de manière permanente comme "disparues" ou de conserver la marque pendant une période de temps - cela est laissé à la discrétion du propriétaire du serveur.
J'aurais/aurais choisi 1 (Déplacé en permanence) Les codes de la série 300 sont censés dire au client qu'ils ont une action à faire.
Je recommanderais un 207 Multi-Status réponse, indiquant qu'il s'agit d'une réponse réussie, mais qu'elle a également potentiellement un deuxième statut obsolète.
Affiner la réponse de @ dret. Il existe deux en-têtes HTTP pertinents pour la dépréciation: Deprecation ( https://tools.ietf.org/html/draft-dalal-deprecation-header- ) et Sunset.
Pour informer les utilisateurs de la dépréciation prévue, l'en-tête HTTP Deprecation doit être utilisé. Cela indique que le point de terminaison sera supprimé dans le futur . Il vous permet également d'indiquer la date à laquelle cela a été annoncé et de décrire d'autres ressources.
Pour informer les utilisateurs de la date d'extinction prévue de la ressource obsolète, l'en-tête Sunset doit être utilisé en plus de l'en-tête Deprecation. Ceci est décrit dans la section # 5 https://tools.ietf.org/html/draft-dalal-deprecation-header-00#section-5 .
Draft # 11 https://tools.ietf.org/html/draft-wilde-sunset-header-11 de l'en-tête Sunset clarifie également cet aspect dans la section 1.4 - https://tools.ietf.org/html/draft-wilde-sunset-header-11#section-1.4 .
Il existe un champ d'en-tête HTTP appelé Sunset qui est destiné à signaler une dépréciation prochaine d'une ressource. https://tools.ietf.org/html/draft-wilde-sunset-header est dans les dernières étapes pour devenir un RFC. Idéalement, votre API doit documenter qu'elle va utiliser Sunset, afin que les clients puissent la rechercher et agir en conséquence, s'ils le souhaitent.