API indisponible ou données en retard : quelle réponse envoyer ?

Le service de stock ne répond plus. Votre API peut encore afficher une copie du catalogue, mais peut-elle confirmer qu'un produit est disponible ? La réponse dépend de l'engagement pris envers le client. Un mode dégradé utile précise ce qui est connu, ce qui reste incertain et ce que le client peut faire ensuite.

Commencer par la garantie attendue

Consulter une description et réserver le dernier exemplaire ne demandent pas les mêmes garanties. Une copie ancienne peut suffire à la première opération, mais pas nécessairement à la seconde.

Le théorème CAP formalise un arbitrage en présence d'une partition réseau. Il ne signifie pas que tout retard, tout verrou ou toute erreur d'API relève d'une partition.

Le contrat de l'API doit néanmoins traiter ces situations concrètes : données anciennes, dépendance absente, résultat inconnu ou travail encore en cours.

Servir une copie quand son ancienneté reste acceptable

Un catalogue mis à jour il y a trente secondes peut rester utile. La réponse doit permettre de comprendre sa fraîcheur lorsque celle-ci influence la décision du client.

L'en-tête HTTP Age décrit l'âge estimé d'une réponse dans le mécanisme de cache. Il ne mesure pas directement le retard des données métier : une réponse produite à l'instant peut contenir une projection ancienne.

Une date d'actualisation ou une version de projection peut donc être nécessaire en complément. Le nom du champ doit préciser ce qui a été mis à jour.

Les directives comme stale-if-error permettent certains usages de réponses périmées selon les conditions du cache. Elles ne doivent pas servir à contourner une exigence de fraîcheur définie pour l'opération.

Refuser avec un statut correspondant à la situation

Un corps d'erreur structuré peut préciser la cause connue et le moyen de reprendre. Il faut éviter d'annoncer une cause certaine lorsque le serveur ne dispose que d'un délai dépassé.

Retry-After peut suggérer une attente dans les situations prévues par HTTP. Ce délai ne garantit pas que le service sera revenu et ne rend pas une opération non idempotente sûre à répéter.

Accepter un travail différé sans annoncer sa réussite

Si le système peut conserver durablement une demande pour la traiter plus tard, il peut répondre 202 Accepted avec une ressource de suivi.

Le client sait alors que la demande a été acceptée, mais que son résultat final n'est pas encore connu. Ce contrat ne contourne pas CAP : il propose une opération avec une autre garantie, celle de la prise en charge différée.

Certains métiers autorisent aussi un service limité pendant une coupure, avec un plafond ou une réservation préalable. Les règles et le risque accepté doivent être définis côté serveur.

Rendre les résultats partiels identifiables

Une recherche peut renvoyer les résultats disponibles tout en signalant qu'une source n'a pas répondu. Le client doit pouvoir distinguer une liste complète d'une réponse partielle.

De même, une référence absente ne signifie pas toujours que l'objet a été supprimé. Il peut être inaccessible, non autorisé ou pas encore synchronisé. Le serveur ne doit affirmer que ce qu'il sait, sans révéler d'informations interdites.

Si une donnée manquante est indispensable à une décision, la masquer ne résout pas le problème. Le parcours doit attendre, refuser ou demander une intervention selon ses règles.

Préparer la reprise et sa vérification

Après le retour de la dépendance, il faut rattraper les projections ou réconcilier les états. Le client doit pouvoir consulter le résultat des opérations restées en attente.

Testez la coupure, le retour du service et une réponse perdue après réussite. Vérifiez aussi les règles de répétition des requêtes.

Une bonne réponse dégradée donne une information utilisable sans promettre davantage que le système ne garantit. Le code, les en-têtes et le corps participent ensemble à ce contrat.

Sources

• RFC 9110, HTTP Semantics, §15.6.4 503 Service Unavailable.
• RFC 9110, §15.6.5, 504 Gateway Timeout.
• RFC 9110, §15.5.13, 412 Precondition Failed.
• RFC 9110, §15.3.3, 202 Accepted.
• RFC 9110, §10.2.3 Retry-After.
• RFC 9111, HTTP Caching, 2022.
• RFC 5861, HTTP Cache-Control Extensions for Stale Content, 2010.
• RFC 9457, Problem Details for HTTP APIs, 2023.
• S. Gilbert & N. Lynch, Brewer's conjecture…, ACM SIGACT News, 2002.
• E. Brewer, CAP Twelve Years Later, IEEE Computer, 2012.