Vue d'ensemble
Une API mal conçue est une bombe à retardement. Dans la banque, c'est une bombe à retardement avec les données financières de vos utilisateurs à l'intérieur. Cette Phase 2 ne portait pas sur le code — elle portait sur le contrat qui garantit que le code, une fois écrit, fera exactement ce qu'il doit faire. Pas plus. Pas moins. Pas autrement.
Le projet
Concevoir les endpoints Transactions et formaliser le contrat OpenAPI : lister, détailler, annoter et supprimer les opérations mensuelles d'un compte bancaire.
Le client
Argent Bank, néobanque en ligne. Phase 2 d'un projet dont la Phase 1 (authentification) avait déjà été livrée avec succès.
Le problème
Des maquettes de transactions disponibles, mais aucun contrat API défini. Sans spécification claire, front-end, back-end et QA risquent trois interprétations différentes du même écran.
L'objectif
Produire un contrat d'API suffisamment précis pour éliminer toute ambiguïté d'implémentation — et suffisamment robuste pour gérer la sécurité, la pagination et l'évolutivité.
Le cœur de ce projet n'est pas du code livré. C'est de l'ambiguïté éliminée. Chaque endpoint défini, chaque schéma formalisé, chaque cas d'erreur documenté est un bug qui n'existera jamais — et un débat d'équipe qui n'aura pas lieu.
Résultats concrets
Un contrat que tout le monde comprend
Endpoints explicites, schémas de données clairs, réponses standardisées. Front, back et QA lisent le même document — et en tirent la même compréhension.
Une spécification directement exploitable
Le document OpenAPI n'est pas un PDF qui dort dans un dossier. Il sert au mock server, aux tests de conformité et à la génération de code.
La sécurité pensée dès la conception
Authentification Bearer, cloisonnement des données par utilisateur, validation des payloads, gestion de la concurrence via ETag — intégrés dans le contrat, pas ajoutés après coup.
Une base qui supporte la croissance
Pagination, tri, filtres, cadre temporel et schémas réutilisables : l'API est conçue pour évoluer au-delà du périmètre initial sans rupture de contrat.
Avant / Après
Le problème
Concevoir une API bancaire n'est pas comme concevoir une API de blog. Chaque endpoint manipule des données financières. Chaque erreur de conception peut exposer les informations d'un utilisateur — ou pire, celles d'un autre.
Le défi de cette Phase 2 tenait en quatre contraintes simultanées :
- La précision. Dans une API de transactions, il n'y a pas de place pour le « à peu près ». Un endpoint qui renvoie trop de données est un risque de sécurité. Un endpoint qui en renvoie trop peu est un problème d'UX. Le contrat doit être chirurgical.
- La sécurité par design. Pas un filtre ajouté après l'implémentation. La sécurité devait être intégrée dans la structure même du contrat : qui accède à quoi, comment, et que se passe-t-il quand quelqu'un essaie d'accéder à ce qui ne lui appartient pas.
- La collaboration multi-équipes. Le contrat devait servir trois publics : les développeurs front qui le consomment, les développeurs back qui l'implémentent et la QA qui le teste. Un seul document, trois usages — zéro ambiguïté.
- L'évolutivité sans rupture. Cette Phase 2 couvre les transactions mensuelles. La Phase 3 ajoutera probablement des virements, de l'historique étendu ou de l'export. Le contrat devait supporter ces extensions sans tout réécrire.
C'est l'intersection de ces quatre exigences qui rend la conception d'API bancaire fondamentalement différente d'un simple CRUD.
Notre approche
Nous avons commencé par les usages — pas par les routes. Chaque endpoint est né d'un besoin réel, pas d'une convention technique.
Phase 1 — Repartir des parcours utilisateur
- Consultation mensuelle par compte : « je veux voir mes opérations du mois »
- Lecture détaillée d'une transaction : « je veux comprendre ce débit »
- Annotation : « je veux catégoriser cette dépense »
- Suppression ciblée : « je veux retirer une note que j'ai ajoutée »
Ces quatre parcours ont défini les quatre groupes d'endpoints — ni plus, ni moins.
Phase 2 — Découper le domaine en ressources propres
- Séparation nette entre comptes, transactions et métadonnées éditables
- Chaque ressource a son périmètre, ses routes et ses schémas
- Pas de super-endpoint qui fait tout — chaque route fait une chose bien
Phase 3 — Formaliser le contrat avec rigueur
- Endpoints définis avec méthodes HTTP appropriées (
GETpour la lecture,PATCHpour les mises à jour partielles,DELETEpour la suppression ciblée) - Schémas de données réutilisables et typés
- Réponses standardisées : succès, erreurs client, erreurs serveur
- Exemples concrets pour chaque cas d'usage
Phase 4 — Intégrer les garde-fous
- Authentification Bearer sur chaque route sensible
- Cloisonnement des données : un utilisateur ne voit que ses propres transactions
- Validation des payloads entrantes
- Gestion de la concurrence via ETag / If-Match pour éviter les écrasements
- Pagination, tri et filtres pour supporter les volumes réels
Phase 5 — Rendre le contrat exploitable
- Document OpenAPI structuré pour être importé dans un mock server (Prism/Stoplight)
- Format compatible avec les outils de test de conformité (Schemathesis/Dredd)
- Organisation qui permet au front de commencer l'intégration avant que le back ne soit terminé
La qualité d'une API ne se mesure pas au nombre de routes. Elle se mesure à la prévisibilité de ses comportements. Un bon contrat rend chaque réponse attendue — y compris les erreurs.
Stack technique
- OpenAPI 3.0 / YAML
- Swagger Editor
- Prism / Stoplight (mock server)
- Schemathesis / Dredd (tests de conformité)
- React + Redux Toolkit / RTK Query (contexte de consommation front)
Le résultat
Le livrable de ce projet est un document. Mais ce document vaut plus que des milliers de lignes de code — parce qu'il garantit que chaque ligne de code écrite ensuite sera la bonne.
- Un contrat OpenAPI complet couvrant l'ensemble du périmètre transactionnel
- Des endpoints précis pour la liste, le détail, l'annotation et la suppression
- Des schémas de données réutilisables et typés
- Des erreurs documentées avec statuts et messages explicites
- Une base directement exploitable en mock server, en tests de conformité et en intégration front
- Un contrat conçu pour évoluer vers de nouveaux cas d'usage sans rupture
Le front-end peut commencer l'intégration immédiatement. Le back-end sait exactement quoi implémenter. La QA sait exactement quoi tester. C'est le pouvoir d'une spécification bien faite.
Ce que ce projet révèle
Ce projet démontre une compétence rare : concevoir une API comme un système de décisions — pas comme un inventaire de routes. Ce qui est exposé, ce qui est modifiable, ce qui doit rester prévisible et ce qui doit rester sûr. Dans un contexte bancaire, cette rigueur de conception n'est pas un luxe. C'est ce qui sépare un produit fiable d'un produit à risque.
Si vous construisez une API qui manipule des données sensibles, si vous avez besoin d'un contrat technique suffisamment précis pour aligner front, back et QA, ou si vous voulez que votre spécification serve réellement à quelque chose — c'est exactement ce travail de conception que nous maîtrisons.