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: