Une demande acceptée doit avoir une issue visible

Un message de réussite dans le portail doit attester l’état sur lequel l’utilisateur s’appuie. Une personne qui attend un rapport terminé a besoin d’un rapport récupérable. L’acceptation de sa création est une étape intermédiaire. Cette distinction détermine les informations que le produit affiche à l’utilisateur.

MDN décrit HTTP 202 comme l’acceptation d’un traitement non terminé. Le travail peut échouer ensuite. Microsoft présente une consultation d’état séparée pour ces flux asynchrones. Le code HTTP de la première réponse ne règle donc pas la question de ce que le portail doit afficher ensuite.

Une même acceptation, deux interfaces

Dans notre portail fictif, le travail de rapport J-73 est accepté. Le modèle est d’abord disponible, puis supprimé avant le traitement. La comparaison suivante décrit deux interfaces possibles, pas un test utilisateur effectué.

Les deux interfaces pourraient avoir reçu la même réponse d’acceptation. Elles donnent pourtant des informations différentes. Dans A, l’acceptation technique peut masquer une attente métier non satisfaite. B garde le travail visible jusqu’à ce que son issue soit connue.

Une consultation d’état réussie peut montrer un échec

Notre API d’exemple renvoie HTTP 200 pour la lecture réussie de la ressource d’état, avec ce contenu :

{"jobId":"J-73","status":"failed","error":{"code":"template-not-found"}}

La consultation a fonctionné ; la création du rapport a échoué. Les noms des champs et la réponse sont nos propres règles d’exemple, pas une obligation pour toutes les API. Une évaluation qui compte seulement les appels HTTP réussis pourrait manquer ce travail. Demandes acceptées, rapports terminés et travaux échoués répondent à des questions différentes.

Si la consultation d’état est elle-même inaccessible, l’état actuel du travail reste inconnu. Le portail ne doit en déduire ni un rapport terminé ni un échec certain. Un nouveau clic doit aussi être relié au travail existant pour que des demandes supplémentaires n’aggravent pas l’incertitude.

Quand l’acceptation suffit comme résultat

Une fonction limitée au dépôt peut remplir sa mission convenue par une acceptation durable. Une confirmation clairement libellée comme acceptation convient alors. De même, une opération entièrement terminée de manière synchrone n’a pas besoin d’un cycle de consultation supplémentaire par principe.

Le portail de rapports poursuit un autre objectif : l’utilisateur veut le fichier. L’évaluation de l’intégration doit donc aller jusqu’à ce résultat et à un parcours d’erreur traçable. Une première réponse rapide est alors une propriété distincte, pas la preuve qu’un rapport est disponible.

Sources

• MDN: 202 Accepted

• Microsoft: Asynchronous Request-Reply pattern