Quel est le code d'état HTTP correct pour: "Cette version de cette API a été abandonnée"?


13

J'ai une API RESTful. Il existe en 3 versions: v1, v2 et v3. Je suis sur le point de publier la v4, et nous avons décidé d'arrêter la v1, ce qui signifie que toutes les demandes à http://example.com/v1/resourceéchoueront, mais les appels à http://example.com/v2/resourcecontinueront de fonctionner.

Quelle est la manière appropriée d'indiquer l'échec? J'ai envisagé d'utiliser un 410 GONEcode d'état, mais cela indique que la ressource n'est plus disponible. La ressource EST probablement toujours disponible, cependant, seulement elle doit être demandée d'une manière différente.

J'ai également envisagé un 400code d'état générique , mais cela semblait aussi bizarre. Y a-t-il une réponse standard à cela?


Il n'y a pas de code d'état HTTP pour l'échec de l'API car les API n'ont rien à voir avec HTTP. Vous dites que la ressource est toujours disponible mais elle doit être demandée d'une autre manière que, dans REST, ce n'est pas la même ressource donc, non, elle n'est pas disponible.
Rob

Réponses:


11

Il ne semble pas y avoir de norme.

La réponse StackOverflow penche vers 410 GONE, mais je pense que 301 MOVED PERMANENTLY est plus approprié.

Pour faire le bon choix, nous devons examiner votre cas spécifique. Si votre objectif est de faire échouer tous les appels vers l'API v1 sans prendre aucune autre action, 410 GONE fonctionne pour cela. Si vous voulez une certaine continuité, comme rediriger le client vers une version plus récente de votre API où leur appel peut réussir, 3XX fonctionne, mais que choisissez-vous? Je pense que si vous essayez d'arrêter l'API v1, 301 MOVED PERMANENTLY indique que mieux que 303 SEE OTHER parce que 301 suggère que toutes les demandes futures devraient être faites à la nouvelle URL alors que 303 n'indique pas si cette situation est ou non permanent.

Je recommanderais de concevoir l'API de telle sorte que chaque version reste rétrocompatible, de sorte que 301 MOVED PERMANENTLY maintienne de manière transparente votre API vivante et à jour chaque fois que vous ajoutez de nouveaux points de terminaison pour de nouvelles versions d'API. Je pense que c'est ce que vous essayez de faire de toute façon.

Codes d'état HTTP

Le code d'état HTTP 302 était à l'origine trop large et est donc devenu incorrectement implémenté / utilisé, donc 303 et 307 ont été faits pour distinguer le cas d'utilisation double de 302. Certaines API utilisent 303 à d'autres fins.

301 MOVED PERMANENTLY - Le code d'état 301 (Moved Permanently) indique que la ressource cible a reçu un nouvel URI permanent et que toute référence future à cette ressource doit utiliser l'un des URI joints.

302 TROUVE - Le code d'état 302 (Trouvé) indique que la ressource cible réside temporairement sous un URI différent. Étant donné que la redirection peut être modifiée à l'occasion, le client doit continuer à utiliser l'URI de demande effective pour les demandes futures.

303 SEE OTHER - Une réponse 303 à une demande GET indique que le serveur d'origine n'a pas de représentation de la ressource cible qui peut être transférée par le serveur via HTTP. Cependant, la valeur du champ Emplacement fait référence à une ressource qui est descriptive de la ressource cible, de telle sorte que faire une demande de récupération sur cette autre ressource peut entraîner une représentation utile aux destinataires sans impliquer qu'elle représente la ressource cible d'origine.

410 GONE - Le code d'état 410 (Gone) indique que l'accès à la ressource cible n'est plus disponible sur le serveur d'origine et que cette condition est susceptible d'être permanente. Si le serveur d'origine 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) doit être utilisé à la place.

Comment les API existantes gèrent-elles cela?

Vous pouvez peut-être prendre une page de l' API Youtube de Google :

Lorsqu'une demande d'API échoue, YouTube renvoie un code de réponse HTTP 4xx ou 5xx qui identifie de manière générique l'échec ainsi qu'une réponse XML qui fournit des informations plus spécifiques sur les erreurs qui ont causé l'échec. Pour chaque erreur, la réponse XML comprend un élément de domaine, un élément de code et éventuellement un élément d'emplacement.

Lectures complémentaires:


2
301 semble dangereux. Cela entraînerait des redirections automatiques vers un endroit qui pourrait ne pas avoir la même signification canonique.
Brandon Yarbrough

Appréciez l'entrée. Tous les codes 3XX indiquent que le client doit effectuer une action supplémentaire (redirection) en fournissant une URL alternative dans l'en-tête Location. Il est intéressant de noter que chaque code a un comportement de redirection légèrement différent; un 303 redirigera un POST vers le nouvel emplacement en tant que GET. Je mettrai certainement à jour cette réponse avec plus d'informations.
perry

1

Les redirections sont idéales pour les ressources qui ont été déplacées. Au lieu d'une redirection permanente 301 (qui indiquerait un changement de nom sans changement d'API), j'utiliserais une redirection 303 "Voir autre".


0

Vous devez toujours prendre en charge l'héritage sans redirection? Même si vous le soutenez toujours et au fond, il est toujours implémenté, le 501 semble plutôt aller de pair avec votre situation. Ceux qui savent pourraient encore l'utiliser, tandis que les randoms verraient le 501 pour la v1.

10.5.2 501 non implémenté

Le serveur ne prend pas en charge les fonctionnalités requises pour répondre à la demande. Il s'agit de la réponse appropriée lorsque le serveur ne reconnaît pas la méthode de demande et n'est pas capable de la prendre en charge pour aucune ressource.

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


0

J'utiliserais 503 avec un message indiquant que le service n'est pas disponible et indiquais d'utiliser la version la plus récente. Ce message peut être renvoyé pour 50% des appels et augmenter progressivement à 100% dans le temps.

Pour une migration transparente, j'utiliserais 308 - Redirection permanente, car cette méthode ne modifie pas le verbe (POST sera POST) contrairement à 301.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.