Opérations longues : 202 Accepted et une ressource de statut

Ce que c'est

La RFC 9110 (citée) définit 202 (Accepted) comme délibérément non engageant : la requête a été acceptée pour traitement, mais ce traitement n'est pas terminé, il pourra encore être refusé plus tard, et HTTP ne dispose d'aucun mécanisme pour renvoyer ultérieurement un code de statut depuis une opération asynchrone. La représentation envoyée avec un 202 devrait décrire le statut actuel de la requête et pointer vers un moniteur de statut (ou l'intégrer). L'AIP-151 de Google (citée) fait de ce moniteur une ressource à part entière : les méthodes susceptibles de prendre un temps significatif renvoient une Operation dotée d'un nom, d'un indicateur done, de metadata pour la progression et les échecs partiels, et, une fois terminée, soit d'un error soit d'un response. Sa règle empirique est qu'un travail de plus d'environ 10 secondes justifie ce motif, et que les opérations peuvent expirer, avec 30 jours suggérés.

Pourquoi c'est important

Bloquer une connexion pendant des minutes échoue à chaque couche : les proxys coupent les connexions inactives, les clients expirent et retentent, et une tâche non idempotente relancée s'exécute deux fois. Une ressource d'opération explicite permet au client de se déconnecter, d'interroger et de se rétablir après son propre redémarrage, et donne au serveur un endroit unique où consigner le résultat.

Comment l'appliquer

• Renvoyer 202 Accepted avec un en-tête Location (ou un lien dans le corps) vers /operations/{id} et inclure la représentation de l'opération dans le corps, afin que le client n'ait pas besoin d'une seconde requête immédiate.
• Modéliser l'opération avec done, metadata (progression, comptages, échecs non fatals) et, une fois terminée, exactement l'un de error ou response ; utiliser la même forme d'erreur que pour les échecs synchrones.
• Accepter une clé d'idempotence fournie par le client sur la requête de démarrage, afin qu'une nouvelle tentative après un 202 perdu renvoie la même opération au lieu d'en démarrer une seconde.
• Prendre en charge l'interrogation avec des indications Retry-After ; proposer un webhook pour les clients capables d'en recevoir un, mais garder l'interrogation comme solution de repli.
• Documenter l'expiration : combien de temps le résultat reste récupérable, et ce que renvoie un GET sur une opération expirée.
• Pour les ressources créées de façon asynchrone, laisser List et Get afficher la ressource avec un état qui la marque comme pas encore utilisable (AIP-151).
• Décider du comportement des opérations parallèles sur une même ressource : les mettre en file d'attente, ou les rejeter avec une erreur de conflit nommant l'opération en cours.

Pièges

Renvoyer 202 puis traiter quand même de façon synchrone. Changer le type de résultat d'une opération existante, ce que l'AIP-151 classe comme un changement cassant. Utiliser 200 avec un corps « pending », ce qui pousse les caches et les clients à considérer la tâche comme terminée. Perdre les enregistrements d'opération au redémarrage, si bien que le client ne peut jamais connaître le résultat. Des points d'accès d'interrogation sans limitation de débit.

Répondre de façon synchrone lorsque le travail est rapide

Décider au niveau de chaque requête, et non par type d'opération, lorsque la latence est bimodale. Exécuter la tâche pendant une durée bornée et, si elle se termine, répondre 200 ou 201 avec le résultat ; sinon, répondre 202 avec la ressource d'opération. La RFC 7240 donne son mot à dire au client : Prefer: wait=N borne le temps qu'il est prêt à attendre, Prefer: respond-async demande d'emblée la voie du 202, et le serveur indique ce qu'il a honoré dans Preference-Applied. Documenter les deux formes de réponse de l'opération et laisser l'auxiliaire d'attente du SDK les normaliser, afin que les appelants ne voient qu'un seul type de résultat. Réserver la conception toujours-202 aux travaux qui sont systématiquement longs.