Développement API-First
Le développement API-first commence par le contrat. GitScrum aide les équipes à coordonner la conception des APIs et à suivre l'implémentation par rapport aux spécifications convenues.
Approche API-First
Concevoir Avant de Construire
WORKFLOW API-FIRST :
┌─────────────────────────────────────────────────────────────┐
│ │
│ TRADITIONNEL (CODE-FIRST) : │
│ ─────────────────────────── │
│ │
│ Backend construit → Frontend attend → Intégration → Reprise│
│ │ │ │
│ └─ Forme de l'API inconnue ───────────┘ │
│ │
│ PROBLÈME : Frontend bloqué, problèmes d'intégration tardifs│
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ API-FIRST : │
│ ────────── │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Concevoir│──→│ Contrat │──→│ Travail │──→│ Intégrer │ │
│ │ l'API │ │ Convenu │ │ Parallèle│ │ & Tester │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │
│ │ ┌────┴────┐ │
│ │ │ │ │
│ │ Frontend Backend │
│ │ (avec mock) (réel) │
│ │ │ │ │
│ │ └────┬────┘ │
│ │ │ │
│ └──────────────┘ │
│ Même contrat │
│ │
│ AVANTAGE : Les deux équipes travaillent en parallèle │
└─────────────────────────────────────────────────────────────┘
Processus de Conception d'API
WORKFLOW DE CONCEPTION D'API :
┌─────────────────────────────────────────────────────────────┐
│ │
│ ÉTAPE 1 : IDENTIFIER LES CONSOMMATEURS │
│ ────────────────────────────────────── │
│ • Qui va utiliser cette API ? │
│ • Frontend web, app mobile, tiers ? │
│ • De quoi ont-ils besoin ? │
│ │
│ ÉTAPE 2 : CONCEVOIR LES ENDPOINTS │
│ ───────────────────────────────── │
│ • Ressources et opérations │
│ • Formes requête/réponse │
│ • Formats d'erreur │
│ • Authentification │
│ │
│ ÉTAPE 3 : DOCUMENTER DANS LA SPEC │
│ ───────────────────────────────── │
│ • OpenAPI pour REST │
│ • GraphQL SDL │
│ • Format lisible par machine │
│ │
│ ÉTAPE 4 : RÉVISER AVEC LES CONSOMMATEURS │
│ ──────────────────────────────────────── │
│ • Partager la spec avec frontend/consommateurs │
│ • Recueillir les retours │
│ • Itérer sur la conception │
│ │
│ ÉTAPE 5 : FINALISER LE CONTRAT │
│ ────────────────────────────── │
│ • La spec convenue devient la source de vérité │
│ • Générer le serveur mock │
│ • Les deux équipes commencent le travail │
└─────────────────────────────────────────────────────────────┘
Spécification OpenAPI
Définition du Contrat
SPÉCIFICATION OPENAPI :
═══════════════════════
openapi: 3.0.0
info:
title: API Commandes
version: 1.0.0
paths:
/orders:
post:
summary: Créer une commande
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCreate'
responses:
'201':
description: Commande créée
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
Avantages de la Spécification
| Avantage | Description |
|---|
| Documentation auto | Générer docs depuis la spec |
| Serveur mock | Tester sans backend réel |
| Validation | Valider requêtes/réponses |
| Génération de code | SDK clients automatiques |
| Tests de contrat | Vérifier conformité |
Serveurs Mock
Développement Parallèle
WORKFLOW AVEC MOCK SERVER
═════════════════════════
SPEC OPENAPI
│
├────────────────────────────────────┐
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ MOCK │ │ BACKEND │
│ SERVER │ │ DEV │
└────┬─────┘ └────┬─────┘
│ │
▼ │
┌──────────┐ │
│ FRONTEND │ │
│ DEV │ │
└────┬─────┘ │
│ │
└─────────────┬──────────────────────┘
│
▼
┌───────────┐
│INTÉGRATION│
│ FINALE │
└───────────┘
Outils de Mock
| Outil | Description |
|---|
| Prism | Mock server OpenAPI |
| WireMock | Mock HTTP flexible |
| Mockoon | Desktop mock server |
| json-server | Mock REST rapide |
Tests de Contrat
Validation Continue
TESTS DE CONTRAT
════════════════
CI/CD PIPELINE :
├── Build
├── Tests unitaires
├── Tests de contrat ← Vérifie la conformité API
│ ├── Réponses matchent la spec
│ ├── Codes statut corrects
│ └── Schémas validés
├── Tests d'intégration
└── Déploiement
Types de Tests de Contrat
NIVEAUX DE VALIDATION
═════════════════════
SCHÉMA :
├── Champs requis présents
├── Types corrects
└── Formats valides (email, date, etc.)
SÉMANTIQUE :
├── Valeurs dans les plages attendues
├── Énumérations valides
└── Relations cohérentes
COMPORTEMENT :
├── Idempotence respectée
├── Erreurs correctement formatées
└── Pagination fonctionne
Workflow GitScrum
Tâches API-First
TÂCHES DE CONCEPTION API DANS GITSCRUM
══════════════════════════════════════
PHASE CONCEPTION :
├── API-001 : Identifier les besoins consommateurs
├── API-002 : Concevoir les endpoints
├── API-003 : Écrire la spec OpenAPI
├── API-004 : Revue avec équipe frontend
└── API-005 : Finaliser et publier le contrat
PHASE IMPLÉMENTATION :
├── API-006 : Configurer le mock server
├── API-007 : [Backend] Implémenter POST /orders
├── API-008 : [Frontend] Intégrer POST /orders (mock)
├── API-009 : [Backend] Tests de contrat
└── API-010 : Intégration frontend-backend réel
Bonnes Pratiques
Conseils pour l'API-First
| Pratique | Bénéfice |
|---|
| Impliquer les consommateurs tôt | API qui répond aux vrais besoins |
| Versionner la spec | Historique des changements |
| Automatiser les tests | Détection précoce des dérives |
| Documenter les décisions | Contexte pour le futur |
| Itérer rapidement | Conception affinée avant code |
Erreurs à Éviter
ANTI-PATTERNS API-FIRST
═══════════════════════
❌ Concevoir en isolation
└── Les consommateurs découvrent tard
❌ Spec trop détaillée trop tôt
└── Temps perdu sur ce qui changera
❌ Ignorer les retours des consommateurs
└── API difficile à utiliser
❌ Ne pas maintenir la spec à jour
└── Divergence contrat/implémentation
❌ Sauter les tests de contrat
└── Régressions non détectées
Solutions Connexes
