Article

REST et CQRS : relier les lectures de l’API aux décisions métier

GET sert souvent les vues de lecture, tandis que les écritures demandent une décision métier. REST et CQRS se combinent sans imposer le même découpage.

La fiche d’une commande affiche son contenu, le nom du client et l’état de livraison. La cliente veut l’annuler. Qui décide si c’est encore possible : la fiche qu’elle vient de lire, ou autre chose ? Avec CQRS, la fiche vient d’un modèle de lecture, et l’annulation est une décision du modèle d’écriture, qui applique les règles des commandes. Une API REST peut présenter les deux ensemble, à condition d’envoyer la demande d’annulation au modèle qui sait la valider.

Une commande fictive, C42, sert de fil de sa lecture à son annulation. Après la fiche que l’API affiche et la demande d’annulation, deux issues sont possibles : une annulation confirmée alors que la liste n’est pas encore à jour, ou un refus parce que la commande a changé entre la lecture et le clic.

Deux modèles derrière une même API

CQRS, pour Command Query Responsibility Segregation, sépare deux responsabilités. Le modèle de lecture prépare les données à afficher, sous la forme la plus commode pour l’écran. Le modèle d’écriture, ou modèle de commande, reçoit les demandes de changement et décide de les accepter ou non, selon les règles du domaine.

REST, de son côté, définit des contraintes d’architecture pour les échanges entre clients et serveurs. Dans une API HTTP, GET demande une représentation d’une ressource, sans demander de changement. Une demande de changement peut notamment utiliser POST, PUT, PATCH ou DELETE.

Les deux idées se rejoignent donc facilement. Un GET peut être servi par le modèle de lecture, et une demande de changement peut déclencher une commande pour le modèle d’écriture. L’un n’impose pas l’autre.

La fiche C42 vient du modèle de lecture

Alice, la cliente, ouvre la fiche de sa commande dans une application, qui interroge une API fictive. La réponse assemble deux sources : le nom de la cliente et la commande elle-même.

GET /commandes/C42 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{"id":"C42","client":"Alice","statut":"preparee",
 "revision_commande":7,
 "actions":[{"nom":"annuler","methode":"POST",
             "href":"/commandes/C42/annulations"}]}

Trois champs comptent pour la suite. statut dit où en est la commande : préparée, pas encore expédiée. Dans ce contrat fictif, revision_commande numérote les versions de la commande, et chaque changement le fait avancer. actions annonce ce que l’application peut demander ensuite, ici une annulation, et à quelle adresse. Ce format est propre à cet exemple ; il ne s’agit pas d’un standard hypermédia.

La fiche indique donc que l’annulation semble possible. Elle ne décide rien pour autant : elle montre la commande telle qu’elle était au moment de la lecture.

L’annulation est décidée par le modèle d’écriture

Alice clique sur « Annuler ». L’application envoie la demande à l’adresse indiquée par la fiche :

POST /commandes/C42/annulations HTTP/1.1
Content-Type: application/json

{"demande":"A42","revision_attendue":7,
 "motif":"demande_client"}

La demande porte son propre identifiant, A42, qui permettra de la suivre. Elle porte aussi la révision que l’application a lue : 7. Entre la lecture de la fiche et le clic, la commande a pu changer, par exemple parce qu’elle vient d’être expédiée. Dans ce contrat, le numéro 7 concerne la commande. Le modèle d’écriture le vérifie avec les règles d’annulation, au moment même où il enregistre sa décision, et non lors d’une vérification séparée qui précéderait l’écriture.

Si C42 est toujours annulable en révision 7, il enregistre l’annulation, fait passer la commande en révision 8 et note les traitements à déclencher ensuite. La réponse rend compte de cette décision :

HTTP/1.1 201 Created
Location: /commandes/C42/annulations/A42
Content-Type: application/json
Cache-Control: no-store

{"id":"A42","etat":"confirmee","commande":"C42",
 "revision_commande":8,"remboursement":"non_requis"}

Le code 201 signifie qu’une ressource a été créée : l’annulation A42 existe désormais, à l’adresse donnée par Location (RFC 9110, §15.3.2). Le contenu de la réponse ajoute que son état est « confirmée » : c’est ce champ, et non le code seul, qui dit la réussite métier. Jusqu’ici, le partage des rôles est net : la fiche a informé, le modèle d’écriture a décidé.

Première issue : la liste affiche encore « préparée »

Juste après la confirmation, Alice revient à la liste de ses commandes, et C42 y apparaît encore comme « préparée ». Dans cet exemple, la liste utilise une projection stockée : une copie des données organisée pour l’affichage, qui peut être mise à jour avec un temps de retard. Tant qu’elle n’a pas reçu la révision 8, elle montre l’état précédent.

Faut-il alors répondre 202 Accepted plutôt que 201 ? 202 signifie que la demande a été acceptée pour traitement, sans que ce traitement soit achevé (RFC 9110, §15.3.3). Il convient à un travail encore en cours, pas automatiquement à toute projection en retard. Or ici, le traitement est achevé : l’annulation est décidée et enregistrée. Seul l’affichage est en retard, et ce retard ne transforme pas la décision déjà réalisée en simple 202. Si l’annulation elle-même devait être examinée plus tard, le statut et la réponse seraient différents.

La réponse doit surtout permettre à l’application de distinguer trois choses : la demande a été acceptée, elle a réussi au sens métier, et elle apparaît dans la liste. Elle peut fournir l’état confirmé ou un moyen de le consulter, en précisant le délai éventuel de la liste. C’est le rôle de l’adresse de A42 : grâce à elle, l’application peut afficher « annulation confirmée » sans attendre que la liste soit à jour.

Seconde issue : la commande a changé, le serveur refuse

Revenons à la fiche en révision 7 et supposons maintenant une autre issue. Juste avant le clic d’Alice, le transporteur a confirmé l’expédition. La commande est passée en révision 8 et n’est plus annulable de façon ordinaire. La demande A42 arrive pourtant avec une révision attendue de 7.

Le service constate l’écart et refuse avec un 409 applicatif, accompagné d’un type de problème qui nomme le conflit (RFC 9110, §15.5.10). L’application relit alors la commande et constate que l’annulation ordinaire n’est plus disponible. Elle ne renvoie pas la même demande en remplaçant simplement 7 par 8 : la demande avait été formée sur une commande en préparation, et la commande expédiée n’offre plus les mêmes possibilités. L’écriture concurrente oblige à réexaminer l’action elle-même, pas seulement le numéro.

Ce refus montre aussi la limite de la fiche. Elle proposait « annuler » parce que la commande semblait annulable au moment de la lecture. Ces contrôles hypermédia aident l’application à découvrir ce qu’elle peut demander, mais le serveur vérifie de nouveau les droits et l’état au moment d’agir. L’application doit donc savoir présenter le refus à Alice, et pas seulement le succès.

Le champ de révision n’est qu’une façon de faire ce contrôle. Dans une autre conception du contrat, la requête de changement vise directement la ressource à protéger et porte un validateur HTTP de cette ressource dans l’en-tête If-Match (RFC 9110, §13.1.1). Une précondition non satisfaite conduit alors normalement à 412, alors qu’un conflit applicatif peut être décrit par 409. Dans les deux cas, le contrôle doit porter sur les données réellement protégées. L’article sur les écritures concurrentes détaille la reprise.

Une API claire relie trois éléments

Le parcours de C42 tient en trois éléments, qu’une API claire relie : l’information disponible, la décision demandée et son résultat. La fiche, servie par le modèle de lecture, a donné à Alice l’information et l’action qu’elle pouvait tenter. La demande d’annulation est partie vers le modèle d’écriture, seul à pouvoir décider, avec la version de la commande qu’elle supposait. La réponse a dit ce qui était confirmé, même quand la liste était en retard, et le refus a obligé à relire plutôt qu’à forcer. Tant que ce contrat est respecté, le modèle interne reste libre d’évoluer.

Cette correspondance entre méthodes HTTP et modèles CQRS aide à organiser le code, mais elle n’est pas une équivalence stricte. Une recherche complexe peut utiliser POST sans devenir une décision métier. Il faut alors préciser ses propriétés, notamment de cache et de reprise.

Approfondissement : sûreté, idempotence et choix du validateur

Trois propriétés de HTTP comptent dès qu’une API va au-delà du parcours de C42.

La première est la sûreté (RFC 9110, §9.2.1). Un GET ne doit pas demander une action comme supprimer une facture, parce que des robots, des caches ou des mécanismes de préchargement consultent des adresses sans intention de déclencher cette action. Le serveur peut néanmoins écrire un journal d’accès : cet effet technique ne change pas le sens de la lecture demandée, car la sûreté de la méthode porte sur ce que le client demande de faire.

La deuxième est l’idempotence : répéter une requête identique produit le même effet demandé qu’une seule exécution, sans promettre la même réponse (RFC 9110, §9.2.2). PUT et DELETE la promettent ; une opération PATCH peut être conçue comme idempotente, mais ne l’est pas automatiquement.

La troisième concerne le choix du validateur. Pourquoi C42 protège-t-elle sa décision par un champ de la commande, plutôt que par l’ETag de la fiche ? Un ETag fort identifie une version précise de la représentation (RFC 9110, §8.8.1) ; or la fiche assemble aussi le nom de la cliente. Si ce nom change, l’ETag de la fiche change, alors que la commande n’a pas bougé. Un contrôle fondé sur lui resterait correct, mais il pourrait refuser des annulations qui ne posent aucun problème. Le numéro de révision de la commande porte exactement sur ce que la décision protège.

Sources

Explorer

Sur le même sujet

Choisis dans l’index d’après les étiquettes de cet article — les plus proches d’abord, hors de sa série. Rien n’est écrit à la main : un article publié demain avec les mêmes étiquettes y prendra place.

Laisser un commentaire

Elle n'est jamais affichée ni publiée. Elle sert à regrouper vos commentaires et, si vous vous inscrivez un jour avec elle, à vous les rendre.

Votre commentaire sera relu avant d'être publié.