Design d'API : REST, GraphQL, gRPC et Choix Stratégiques
#api#architecture#rest#graphql#grpc
Les APIs sont les contrats entre systèmes. Le choix du style d'API, de la stratégie de versionnement et du modèle de gouvernance façonne la collaboration entre équipes et l'évolution des systèmes. C'est une décision architecturale, pas seulement technique.
Comparaison des styles d'API
| Aspect | REST | GraphQL | gRPC |
|---|---|---|---|
| Protocole | HTTP/1.1 ou HTTP/2 | HTTP (endpoint unique) | HTTP/2 |
| Format de données | JSON (typiquement) | JSON | Protobuf (binaire) |
| Schema | OpenAPI/Swagger (optionnel) | SDL (obligatoire) | Fichiers proto (obligatoire) |
| Découvrabilité | HATEOAS, docs | Introspection intégrée | Partage de fichiers proto |
| Over-fetching | Problème courant | Résolu par conception | Field masks (optionnel) |
| Under-fetching | Multiples allers-retours | Requête unique | Conçu par RPC |
| Streaming | Limité (SSE, WebSocket) | Subscriptions | Streaming bidirectionnel |
| Support navigateur | Natif | Natif | Nécessite un proxy (gRPC-web) |
| Cache | Cache HTTP intégré | Complexe (requêtes POST) | Implémentation custom |
| Courbe d'apprentissage | Faible | Moyenne | Moyenne-Haute |
Quand utiliser quoi
- REST -- APIs publiques, CRUD simple, quand le cache HTTP compte, compatibilité large
- GraphQL -- requêtes pilotées par le client, apps mobiles avec contraintes de bande passante, agrégation de backends
- gRPC -- communication inter-services, haute performance, cas de streaming
Stratégies de versionnement
| Stratégie | Exemple | Avantages | Inconvénients |
|---|---|---|---|
| Chemin URL | /api/v2/users | Simple, explicite | Pollution d'URL |
| Paramètre de requête | /api/users?version=2 | Facile par défaut | Facile à manquer |
| Header | Accept: application/vnd.api.v2+json | URLs propres | Cache, plus dur à tester |
| Sans versionnement (évolution) | Ajouter des champs, jamais supprimer | Pas de gestion de version | Discipline stricte requise |
Approche recommandée : versionnement par URL pour les APIs externes (clarté), évolution pour les APIs internes (moins d'overhead).
Patterns API Gateway
Une API gateway se place entre les clients et les services backend :
- Routage -- diriger les requêtes vers le bon service
- Authentification -- valider les tokens avant d'atteindre les backends
- Rate limiting -- protéger les backends contre les abus
- Transformation -- agréger ou remodeler les réponses
- Cache -- réduire la charge backend pour les requêtes répétées
- Monitoring -- logging et métriques centralisés
Options populaires : Kong, AWS API Gateway, GCP API Gateway, Traefik, Envoy.
tadata
Extrait de la fiche « OWASP API Security Top 10, Part 2: Testing, GraphQL, Rate Limits, Tokens » · Demander la fiche complète
Design API-First
Concevoir l'API avant d'écrire le code d'implémentation :
- Définir le contrat (spec OpenAPI, schéma GraphQL, ou fichier proto)
- Générer des serveurs mock pour que les équipes frontend démarrent immédiatement
- Générer automatiquement les SDKs clients
- Implémenter le backend selon le contrat
- Les tests de contrat valident la conformité
APIs internes vs externes
| Aspect | APIs internes | APIs externes |
|---|---|---|
| Audience | Vos propres services/équipes | Développeurs tiers |
| Versionnement | Peut être plus agressif | Doit être conservateur |
| Breaking changes | Coordination inter-équipes | Périodes de dépréciation requises |
| Authentification | Service mesh, mTLS | Clés API, OAuth 2.0 |
| Rate limiting | Basé sur la confiance | Strict, par paliers |
| Documentation | Peut être informelle | Doit être exhaustive |
tadata
| Algorithm | Rule | Behaviour |
|---|---|---|
| Fixed window | count_([t_0, t_0+W)) ≤ L | simple; allows 2L at a window boundary |
| Sliding window | count_((t-W, t]) ≤ L | smooth; used by most cloud WAF rate rules |
| Token bucket | tokens = min(B, tokens + r Δ t) | rate r with bursts up to B; each request spends one token |
Extrait de la fiche « WAF and API Gateway Configuration » · Demander la fiche complète