7 min lecture • Guide 752 of 877
Meilleures Pratiques de Développement d'API
Les APIs sont des contrats entre systèmes. GitScrum aide les équipes à planifier, suivre et livrer le travail API avec une documentation et des tests appropriés.
Planification d'API
Stories API dans GitScrum
STRUCTURE DE STORY API :
┌─────────────────────────────────────────────────────────────┐
│ API-123 : Endpoint Création d'Utilisateur │
├─────────────────────────────────────────────────────────────┤
│ │
│ En tant que consommateur d'API │
│ Je peux créer un nouvel utilisateur via POST /api/v1/users │
│ Afin d'intégrer des utilisateurs par programmation │
│ │
│ ═══════════════════════════════════════════════════════════ │
│ │
│ SPÉCIFICATION ENDPOINT : │
│ │
│ Méthode : POST │
│ Chemin : /api/v1/users │
│ Auth : Token Bearer requis │
│ │
│ Corps de Requête : │
│ { │
│ "email": "utilisateur@exemple.com", │
│ "name": "Jean Dupont", │
│ "role": "member" │
│ } │
│ │
│ Réponse Succès (201) : │
│ { │
│ "id": "usr_abc123", │
│ "email": "utilisateur@exemple.com", │
│ "name": "Jean Dupont", │
│ "role": "member", │
│ "created_at": "2024-01-15T10:30:00Z" │
│ } │
│ │
│ Réponses Erreur : │
│ 400 - Entrée invalide (champ manquant, format invalide) │
│ 401 - Authentification requise │
│ 403 - Permissions insuffisantes │
│ 409 - Email déjà existant │
│ │
│ ═══════════════════════════════════════════════════════════ │
│ │
│ CRITÈRES D'ACCEPTATION : │
│ ☐ Endpoint accepte les données utilisateur valides │
│ ☐ Retourne 201 avec l'utilisateur créé │
│ ☐ Valide le format email │
│ ☐ Rejette les emails en double (409) │
│ ☐ Requiert l'authentification │
│ ☐ Documentation mise à jour │
│ ☐ Tests couvrent le happy path et les erreurs │
└─────────────────────────────────────────────────────────────┘
Checklist de Conception API
PRINCIPES DE CONCEPTION API :
┌─────────────────────────────────────────────────────────────┐
│ │
│ CONVENTIONS DE NOMMAGE : │
│ │
│ ✅ Les ressources sont des noms, pluriels : │
│ /users, /projects, /tasks │
│ │
│ ✅ Utiliser kebab-case pour mots multiples : │
│ /project-members, /time-entries │
│ │
│ ✅ Imbriquer pour les relations : │
│ /projects/{id}/tasks │
│ /users/{id}/notifications │
│ │
│ ❌ Ne pas utiliser de verbes dans le chemin : │
│ /getUsers → GET /users │
│ /createProject → POST /projects │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ MÉTHODES HTTP : │
│ │
│ GET - Récupérer ressource(s) │
│ POST - Créer nouvelle ressource │
│ PUT - Remplacer ressource entière │
│ PATCH - Mettre à jour partie de ressource │
│ DELETE - Supprimer ressource │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ CODES DE STATUT : │
│ │
│ 200 OK - GET/PUT/PATCH réussi │
│ 201 Created - POST réussi │
│ 204 No Content - DELETE réussi │
│ 400 Bad Request - Entrée invalide │
│ 401 Unauthorized - Pas d'auth │
│ 403 Forbidden - Pas de permission │
│ 404 Not Found - Ressource n'existe pas │
│ 409 Conflict - Doublon/conflit │
│ 422 Unprocessable - Validation échouée │
│ 500 Server Error - Notre faute │
└─────────────────────────────────────────────────────────────┘
Versioning d'API
Stratégie de Version
APPROCHES DE VERSIONING API :
┌─────────────────────────────────────────────────────────────┐
│ │
│ OPTION 1 : VERSION DANS L'URL │
│ ───────────────────────────── │
│ /api/v1/users │
│ /api/v2/users │
│ │
│ ✅ Le plus explicite │
│ ✅ Facile à router et cacher │
│ ✅ Visible dans les logs │
│ │
│ OPTION 2 : VERSION DANS LE HEADER │
│ ───────────────────────────────── │
│ Accept: application/vnd.api.v1+json │
│ │
│ ✅ URLs propres │
│ ❌ Moins visible │
│ │
│ RECOMMANDATION : │
│ Utiliser la version dans l'URL pour la clarté │
└─────────────────────────────────────────────────────────────┘
Gestion des Changements Cassants
CYCLE DE VIE DE VERSION
═══════════════════════
v1 ACTIVE v2 DÉVELOPPEMENT
│ │
▼ ▼
┌────────┐ ┌────────┐
│ v1 │─────────│ v2 │
│ stable │ │ beta │
└────────┘ └────────┘
│ │
│ LANCEMENT v2 │
▼ ▼
┌────────┐ ┌────────┐
│ v1 │ │ v2 │
│ dépréc.│─────────│ stable │
└────────┘ └────────┘
│
│ SUNSET v1 (6-12 mois)
▼
┌────────┐
│ v1 │
│ retiré │
└────────┘
Tests d'API
Niveaux de Test
PYRAMIDE DE TESTS API
═════════════════════
┌───────────┐
│ End-to-End│ Peu
│ Tests │ (workflows complets)
└─────┬─────┘
│
┌───────┴───────┐
│ Integration │ Moyen
│ Tests │ (API + dépendances)
└───────┬───────┘
│
┌───────────┴───────────┐
│ Unit Tests │ Beaucoup
│ (logique métier) │ (rapide, isolé)
└───────────────────────┘
Tests Automatisés
TESTS REQUIS PAR ENDPOINT
═════════════════════════
HAPPY PATH :
├── Requête valide → Réponse 2xx
├── Données correctes retournées
└── Effet de bord vérifié (création, etc.)
VALIDATION :
├── Champ requis manquant → 400
├── Format invalide → 400
├── Valeur hors limites → 400
└── Message d'erreur clair
AUTHENTIFICATION/AUTORISATION :
├── Sans token → 401
├── Token invalide → 401
├── Permission insuffisante → 403
└── Accès à ressource d'autrui → 403/404
CAS LIMITES :
├── Ressource inexistante → 404
├── Doublon → 409
├── Pagination vide → 200 avec data: []
└── Rate limit dépassé → 429
Documentation d'API
Contenu Essentiel
DOCUMENTATION COMPLÈTE
══════════════════════
PAR ENDPOINT :
├── Méthode HTTP et chemin
├── Description courte
├── Paramètres (path, query, body)
├── Headers requis
├── Exemple de requête
├── Réponses possibles avec codes
├── Exemples de réponse
└── Erreurs courantes
GÉNÉRAL :
├── Authentification (comment obtenir token)
├── Rate limiting (limites, headers)
├── Pagination (format, paramètres)
├── Erreurs (format standard)
├── Changelog (historique versions)
└── Guide de démarrage rapide
Outils de Documentation
| Outil | Usage |
|---|---|
| OpenAPI/Swagger | Spécification standard |
| Postman | Collections et tests |
| Redoc | Documentation élégante |
| Slate | Documentation statique |
Monitoring et Observabilité
Métriques à Suivre
MÉTRIQUES API ESSENTIELLES
══════════════════════════
DISPONIBILITÉ :
├── Uptime (cible : 99.9%)
├── Taux d'erreurs 5xx
└── Santé des dépendances
PERFORMANCE :
├── Temps de réponse (p50, p95, p99)
├── Débit (requêtes/seconde)
└── Taille des réponses
USAGE :
├── Requêtes par endpoint
├── Requêtes par consommateur
├── Endpoints les plus utilisés
└── Tendances dans le temps
ERREURS :
├── Taux d'erreurs par code
├── Top des erreurs
├── Erreurs par endpoint
└── Patterns d'erreurs