Comment choisir un code de statut HTTP dans REST pour "Pas encore prêt, réessayer plus tard"?)?
Je développe une API RESTful dans laquelle http://server/thingyapi/thingyblob/1234 renvoie le fichier (aka "blob") associé au # 1234 à télécharger. Mais il se peut que la demande soit faite à un moment où le fichier n’existe pas sur le serveur mais très certainement sera disponible ultérieurement. Il existe un traitement par lots sur le serveur qui génère tous les blobs pour tous les trucs. Thingy 1234 existe déjà et ses données, autres que le blob, sont déjà disponibles. Le serveur n'a pas encore généré le blob de thingy 1234.
Je ne veux pas retourner 404; c'est pour les trucs qui n'existent pas. C'est une chose qui existe, mais son blob n'a pas encore été généré. Un peu comme une vidéo de YouTube qui "traite". Je ne pense pas que les codes de redirection seraient appropriés non plus; il n'y a pas "d'autre" URL à essayer.
Quel est le code de statut HTTP correct à renvoyer dans un tel cas?
Je suggère 202 - Accepted. De la documentation :
La demande a été acceptée pour traitement, mais le traitement n'est pas terminé. [...] Son but est de permettre à un serveur d'accepter une demande pour un autre processus (peut-être un processus par lots qui n'est exécuté qu'une fois par jour)
Le "problème", tel qu'il est, est du côté du serveur: le client a fait une requête bien formée, mais le serveur ne peut pas y répondre. Donc, je suis enclin à une "erreur de serveur", code d'état 5xx.
Quoth RFC 7231 (norme HTTP actuelle, soulignement ajouté):
La classe de code d'état 5xx (Erreur de serveur) indique que le serveur est conscient qu'il a commis une erreur ou est incapable d'effectuer la méthode demandée . Sauf en cas de réponse à une demande HEAD, le serveur DEVRAIT envoyer une représentation contenant une explication de la situation d'erreur, et indiquer s'il s'agit d'une temporaire ou condition permanente.
Remarque
- "erred ou est incapable d'exécuter la requête": malgré le titre "Erreur de serveur", elles ne sont pas uniquement destinées aux erreurs de serveur.
- " temporaire ou permanent": ces codes conviennent aux ressources temporairement indisponibles, comme le vôtre.
Parmi les codes disponibles, je dirais 503, "Service indisponible" était la meilleure solution:
Le code d'état 503 (service non disponible) indique que le serveur est actuellement incapable de traiter la demande en raison d'une surcharge temporaire ou d'une maintenance planifiée, qui sera probablement réduite après un certain délai. Le serveur PEUT envoyer un champ d’en-tête Retry-After ... pour suggérer une période de temps appropriée au client pour attendre avant de réessayer la demande.
Remarque:
- "sera probablement allégé après un certain délai": vrai pour votre cas.
- "surcharge temporaire": ce n'est pas pédagogiquement vrai pour votre cas. Mais, pourrait-on dire, si votre serveur était beaucoup plus rapide, le traitement par lots aurait déjà été effectué lorsque le client a fait la demande, de sorte qu'il est une sorte de "surcharge": le client est demander des ressources plus rapidement que le serveur ne peut les rendre disponibles.
- La nouvelle tentative convient à votre service, votre réponse doit donc inclure un
Retry-Aftervaleur. Vous pouvez indiquer comme valeur l'heure d'achèvement estimée de la prochaine exécution du processus de traitement par lots ou l'intervalle d'exécution du processus de traitement par lots.
Définir votre propre code de statut 5xx (591, par exemple), bien que autorisé , ait une mauvaise sémantique:
un client DOIT comprendre la classe de tout code d'état, comme indiqué par le premier chiffre, et traiter un code d'état non reconnu comme étant équivalent au code d'état x00 de cette classe
Les clients traiteraient votre propre code d'état comme 500, "Erreur interne du serveur" , ce qui ne serait pas correct.
Je pense que 423 - Verrouillé peut être utilisé à cette fin:
Le code d'état 423 (verrouillé) signifie que la ressource source ou cible d'une méthode est verrouillée. Cette réponse DEVRAIT contenir un code de précondition ou de post-condition approprié, tel que "lock-token-submit" ou "no-conflicting-lock".
Une autre option: 503 - Service Unavailable.
Je ne veux pas retourner 404; c'est pour les trucs qui n'existent pas.
L'URL ne correspond pas à une demande d'un objet.
http://server/thingyapi/thingyblob/1234
Le client demande un objet, qui n'existe pas. Si cela existait, vous le leur donneriez.
404.
Puisque votre ressource n'est pas prête, vous savez probablement quand (approximativement) elle sera disponible et quand le client pourra réessayer sa demande. Cela signifie que vous voudrez peut-être utiliser en-tête Retry-After . Cet en-tête est valide avec 503 (service non disponible), ce qui signifie qu'un site entier est en panne pour maintenance et des réponses 3xx (redirection).
À mon avis, 302 (trouvé) avec l'en-tête Retry-After serait la meilleure option, mais je ne suis pas sûr si le champ Emplacement de l'en-tête de réponse peut être égal à l'URL de la demande. C'est une redirection circulaire, de toute façon.
409 Conflit
Indique que la demande n'a pas pu être traitée en raison d'un conflit dans la demande, tel qu'un conflit de modification dans le cas de plusieurs mises à jour. [Source Wikipedia.]
Cela pourrait être approprié.
Si vous ne pouvez pas répondre à la demande en renvoyant les données, alors ce n'est pas un succès. Je pense que 202 suggère que le serveur a mis la demande en file d'attente et il l'exécutera plus tard. Mais dans votre cas, la demande concerne les données maintenant et a échoué. Si vous réessayez plus tard, il s'agit d'une demande différente.
Je pense que vous avez un conflit .. vous voulez les données .. mais elles sont éditées/mises à jour. Ce serait également le cas si Thingy1234 existait déjà et avait déjà été téléchargé avec succès auparavant, mais il était en train de le modifier était indisponible pendant le montage.
501 - Non implémenté
Exactement comment ça sonne. Une fonctionnalité qui n'est pas encore implémentée, mais implique une disponibilité future.
Voici un lien vers un résumé des erreurs 5xx .