En production, la plupart des API ne cassent pas d’abord à cause du trafic. Elles cassent lorsqu’elles ne représentent plus assez clairement le workflow pour que le produit, l’exploitation et les autres systèmes puissent leur faire confiance.
Dans les produits orientés workflows, le vrai travail consiste à décider quelles transitions sont autorisées, à quel moment les effets de bord partent, et quel niveau d’incohérence un client doit absorber.
Le problème
Des endpoints CRUD génériques finissent par concentrer trop de responsabilités dans une seule écriture. À mesure que les règles augmentent, la validation dérive entre clients, le comportement des partenaires fuit dans le contrat public et les équipes support perdent un modèle fiable pour expliquer l’état réel du système.
Ce qui casse en pratique
- Des parcours multi-étapes acceptent des écritures valides sur le plan syntaxique mais interdites pour l’état courant.
- Les clients frontend reconstruisent localement des règles métier et dérivent du backend.
- Des effets de bord comme les emails, les synchronisations partenaires ou la génération documentaire partent avant que l’écriture autoritaire soit durablement enregistrée.
- Les échecs d’intégration remontent sous forme d’erreurs API vagues parce qu’aucun contrat interne stable ne sépare la logique métier des adaptateurs partenaires.
Décisions de conception
- Modéliser les endpoints d’écriture autour des transitions plutôt que d’updates génériques afin que le contrat reflète l’intention métier.
- Persister l’état faisant autorité avant de déclencher les effets de bord afin que retries et replays s’appuient sur des données durables.
- Cacher la variabilité des partenaires derrière des contrats de services internes pour garder une API publique prévisible.
- Renvoyer des catégories d’erreurs explicites pour conflits de transition, validation et retries sûrs afin que produit et support puissent agir.
Arbitrages
- Une API orientée transitions crée plus d’endpoints et de code service qu’un design CRUD.
- Des garde-fous backend plus forts réduisent l’ambiguïté mais obligent à aligner plus tôt les équipes produit sur les règles d’état.
- Séparer les effets de bord des écritures améliore la récupération mais exige files, audit et outillage opérateur.
Patterns de production
- Clés d’idempotence sur les écritures susceptibles d’être rejouées par des clients ou workers.
- Garde de transition explicite ou machine à états plutôt qu’un endpoint d’update ouvert.
- Patterns outbox ou table d’événements pour publier les effets de bord après l’écriture durable.
- Correlation IDs et événements d’audit sur chaque transition métier importante.
Ce que je ferais différemment
- Introduire plus tôt des tests de contrat sur les endpoints exposés aux intégrations pour détecter la dérive de réponse.
- Suivre les catégories d’échec par transition comme métriques à part entière au lieu de s’appuyer uniquement sur des dashboards 4xx/5xx.
- Donner aux opérateurs des outils de replay orientés transition au lieu de réutiliser des actions d’admin génériques.