1. Contexte
• Entreprise: Argent Bank, néobanque en ligne.
• Équipe: Sébastien (front-end), cheffe de projet (Mila), CTO (Avery), backend déjà en place (Swagger fourni).
• Livrables de la phase 2: document d’API (OpenAPI/Swagger YAML) pour les transactions: liste mensuelle groupée par compte, vue détaillée, ajout/modification/suppression d’informations associées aux transactions; exemples de requêtes/réponses et codes d’erreur.
• Point de départ: maquettes de la page Transactions, authentification et profil réalisés en phase 1, documentation Swagger existante pour les routes d’auth et profil.
2. Besoin
• Définir des routes REST sécurisées pour consulter les transactions du mois en cours (groupées par compte) et gérer les informations associées (notes, catégories, tags, libellés…).
• Fournir une spécification complète OpenAPI 3.0 exportable en YAML (Swagger Editor).
• Garantir des réponses performantes, paginées/filtrées, avec schémas de données clairs et codes d’erreur cohérents.
3. Client
• Utilisateurs finaux d’Argent Bank souhaitant parcourir et annoter leurs transactions mensuelles.
• Équipe backend pour implémenter les routes selon un contrat clair et testable.
• QA/Produit pour valider les cas d’usage via un mock server généré depuis le YAML.
4 Objectifs
4.1 Fonctionnels
• Visualiser toutes les transactions du mois en cours, groupées par compte.
• Visualiser les détails d’une transaction spécifique.
• Ajouter, modifier ou supprimer des informations associées à une transaction (sans créer/supprimer la transaction elle-même).
• Filtrer/chercher (catégorie, type, montant, texte) et trier (date/montant).
4.2 Techniques
• Authentification Bearer JWT, accès limité aux comptes de l’utilisateur (401/403).
• Pagination, tri et filtres normalisés; paramètres de période avec month=YYYY-MM (ou from/to).
• Mises à jour partielles via PATCH idempotentes et journalisées (audit).
• Schémas OpenAPI réutilisables, exemples exhaustifs, et codes d’erreur standardisés (400/401/403/404/409/422/429/500).
5. Contraintes / défis
• Cohérence avec le modèle existant (comptes/transactions) et compatibilité future (versions d’API).
• Performance sur de grands volumes (pagination, index, cache HTTP/ETag).
• Gestion des fuseaux horaires et bornes mensuelles (UTC vs locale).
• Concurrence (contrôle d’édition, ETag/If-Match pour éviter les écrasements).
• Sécurité (RBAC, rate limiting, validation stricte des payloads, journalisation).
6. Processus / méthodologie
6.1 Analyse
• Étude des maquettes transactions et des parcours: liste mensuelle par compte → détail → annotation/édition → retour liste.
• Modèle REST pressenti: ressources accounts et transactions, avec endpoints de liste par compte et endpoints de détail/édition par transaction.
• Paramètres de période: month=YYYY-MM par défaut (mois courant), alternatives from/to ISO 8601 si besoin d’étendre la plage.
6.2 Découpage en issues (GitHub)
• Définir le modèle de données (schémas Transaction, TransactionMetadata).
• Spécifier les endpoints et paramètres (liste, détail, patch metadata, suppression d’un champ).
• Rédiger le YAML OpenAPI (composants, réponses types, erreurs).
• Générer un mock server et valider via Swagger Editor + Schemathesis/Dredd.
• Revue technique backend + ajustements (versionnage /v1).
6.3 Architecture et logique
• Endpoints proposés (noms indicatifs):
- Liste mensuelle (par compte): GET /v1/accounts/{accountId}/transactions?month=YYYY-MM&page=&pageSize=&sort=&type=&category=&q=
- Détail transaction: GET /v1/transactions/{transactionId}
- Mise à jour d’informations: PATCH /v1/transactions/{transactionId}/metadata (ex: category, labels[], note, merchantName).
- Suppression d’une information précise: DELETE /v1/transactions/{transactionId}/metadata/{field} (ex: note, category).
• Réponses paginées avec enveloppe: items[], page, pageSize, total, links (HATEOAS optionnel).
• Groupement par compte géré soit côté UI (un appel par compte) soit via un agrégat: GET /v1/reports/transactions?month=YYYY-MM&groupBy=account (optionnel).
6.4 Choix techniques (justification)
• Séparer liste (scopée au compte) et détail (globale) pour des URLs stables et un cache efficace.
• PATCH pour mises à jour partielles de metadata (évite de ré-envoyer toute la ressource).
• Paramètre month=YYYY-MM simple et couvrant 90% des cas; from/to pour besoins avancés.
• Codes d’erreur riches: 422 (validation), 409 (conflit de version), 429 (rate limit).
ste.
• ETag/If-Match pour contrôle de concurrence et possibilité de 412 Precondition Failed.
6.5 Flux principaux
• Lister (mois en cours): GET /v1/accounts/{accountId}/transactions?month=2025-11&page=1&pageSize=50&sort=-date → 200 avec items[] et métadonnées de pagination.
• Détails: GET /v1/transactions/tx123 → 200 avec toutes les propriétés immuables + metadata éditable.
• Ajouter/modifier info: PATCH /v1/transactions/tx123/metadata body: { "category": "Groceries", "note": "Courses du week-end" } → 200 et nouvelle version ETag.
• Supprimer une info: DELETE /v1/transactions/tx123/metadata/note → 204 (ou 200 avec ressource mise à jour).
6.6 Tests et qualité
• Validation du contrat via Swagger Editor (lint), Schemathesis/Dredd (tests de conformité).
• Exemples complets de requêtes/réponses (success/erreurs) dans le YAML pour faciliter QA et front-end (MSW).
• Nommage et statuts HTTP cohérents, schémas réutilisables dans components/schemas et components/responses.
7. Analyse
• La séparation nette liste/détail/metadata simplifie le cache, la sécurité et l’évolution; le paramètre month cadre l’usage principal et garde les payloads légers; PATCH et DELETE apportent une granularité simple pour les annotations sans altérer la transaction d’origine.
8. Choix techniques
• OpenAPI 3.0 (YAML) avec composants factorisés (Transaction, TransactionMetadata, Error, Pagination).
• Auth Bearer standard, pagination paramétrique, tri (sort=-date), filtres (type, category, q).
• Contrôle de concurrence avec ETag; erreurs 400/401/403/404/409/412/422/429/500 documentées et exemplifiées.
9. Logique de résolution
• Partir des parcours utilisateurs, cartographier les ressources, puis définir endpoints, paramètres et schémas; valider via mock, tester les cas limites (mois sans données, filtres vides, champs metadata inconnus), itérer avec le backend avant gel du contrat v1.
10. Stack utilisée
• Spécification: OpenAPI 3.0, Swagger Editor (export YAML).
• Mock/Tests contrat: Prism ou Stoplight, Schemathesis/Dredd.
• Côté front (référence): React + Redux Toolkit/RTK Query pour consommer les endpoints et gérer cache/pagination.
11. Résultat final
• Document YAML Swagger v1 prêt à l’implémentation, avec schémas, paramètres, exemples et codes d’erreur.
• Ensemble cohérent d’endpoints couvrant: liste mensuelle par compte, détail transaction, CRUD d’informations associées (via PATCH/DELETE).
• Base solide pour l’implémentation backend, les tests QA et l’intégration front (types générés, MSW).