Quel est le code de statut HTTP correct pour: "Cette version de cette API a été abandonnée"?
J'ai une API RESTful. Il en existe 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 adressées à http://example.com/v1/resource échoueront, mais que les appels à http://example.com/v2/resource continueront de fonctionner.
Quelle est la manière appropriée d'indiquer un échec? J'ai envisagé d'utiliser un code de statut 410 GONE, mais cela indique que la ressource n'est plus disponible. La ressource est probablement IS toujours disponible, mais elle doit être demandée autrement.
J'ai également envisagé un code de statut générique 400, mais cela semblait aussi étrange. Y at-il une réponse standard pour cela?
Il ne semble pas y avoir de norme.
Le StackOverflow answer se penche vers 410 GONE, mais je pense que 301 MOVED PERMANENTLY est plus approprié.
Pour faire le bon choix, nous devons examiner votre cas particulier. Si votre objectif est que tous les appels passés à API v1 échouent sans autre action, 410 GONE fonctionne pour cela. Si vous souhaitez une certaine continuité, telle que la redirection du client vers une version plus récente de votre API où l'appel peut aboutir, 3XX fonctionne, mais que choisissez-vous? Je pense que si vous essayez de fermer API v1, 301 MOVED PERMANENTLY aide à indiquer que mieux que 303 VOIR AUTRE car 301 suggère que toutes les futures demandes doivent être adressées à 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 compatible avec les versions antérieures, de sorte que 301 MOVED PERMANENTLY maintienne de manière transparente votre API en vie et à jour lorsque 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 de statut HTTP 302 était à l’origine trop large et a donc été mal utilisé/implémenté. Par conséquent, les codes 303 et 307 ont été différenciés des cas à double usage de 302. Certaines API utilisent 303 à d'autres fins.
301 DÉPLACÉ DE MANIÈRE PERMANENTE - Le code d'état 301 (déplacé de façon permanente) indique qu'un nouvel URI permanent a été attribué à la ressource cible et toute référence future à cette ressource doit d'utiliser l'un des URI inclus.
302 FOUND - Le code d'état 302 (trouvé) indique que la ressource cible réside temporairement sous un autre URI. Étant donné que la redirection peut être modifiée à l'occasion, le client doit continuer à utiliser l'URI de demande effectif pour les demandes futures.
303 VOIR AUTRE - Une réponse 303 à une demande GET indique que le serveur d'origine ne dispose pas d'une représentation de la ressource cible pouvant être transférée par le serveur. sur HTTP. Toutefois, la valeur du champ Emplacement fait référence à une ressource descriptive de la ressource cible, de sorte qu'une requête d'extraction sur cette autre ressource peut donner 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 de être permanent. 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 (non trouvé) doit être utilisé à la place.
Comment les API existantes gèrent-elles cela?
Peut-être que vous pouvez prendre une page de Google Youtube API :
Lorsqu'une requête d'API échoue, YouTube renvoie un code de réponse HTTP 4xx ou 5xx identifiant de manière générique l'incident, ainsi qu'une réponse XML fournissant des informations plus spécifiques sur les erreurs ayant provoqué l'incident. 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.
- API BigCommerce utilise 302 FOUND.
- Atlassian REST Directives de l'API indique à 301 DÉPLACÉ DE FAÇON PERMANENTE un sous-code décrivant l'erreur en détail. Ceci est similaire à l'approche de l'API Youtube.
Lectures complémentaires:
Les redirections sont idéales pour les ressources déplacées. Au lieu d'une redirection permanente 301 (qui indiquerait un changement de nom sans modifications de l'API), j'utiliserais une redirection 303 "Voir autre".
Besoin de continuer à supporter les héritages sans redirections? Même si vous le soutenez toujours et que, au fond, il est toujours mis en œuvre, le 501 semble plutôt bien au contact de votre situation. Ceux qui sont au courant pourraient toujours l'utiliser, tandis que les random verraient le 501 pour v1.
10.5.2 501 non implémenté
Le serveur ne prend pas en charge la fonctionnalité requise pour répondre à la demande. C'est la réponse appropriée lorsque le serveur ne reconnaît pas la méthode de requête et n'est pas capable de la prendre en charge pour aucune ressource.
Je voudrais utiliser 503 avec un message que le service est indisponible et indiquer d'utiliser la version plus récente. Ce message peut être renvoyé pour 50% des appels et progressivement augmenter à 100%.
Pour une migration transparente, je voudrais utiliser 8 - Redirection permanente, car cette méthode ne modifie pas le verbe (POST sera POST) contrairement à 301.