Conception d'API
Concevez le contrat avant l'implémentation.
Quand l'utiliser
Utilisez-le lorsque l'utilisateur :
- conçoit une nouvelle API ou interface ;
- modifie un contrat existant ;
- définit des schémas de requête/réponse ;
- révise la gestion des erreurs, l'authentification, la pagination ou le versioning ;
- s'intègre avec un service tiers ;
- demande "à quoi devrait ressembler cet endpoint ?".
1. Clarifier le contrat
Identifiez :
- qui appelle l'API : frontend, mobile, service, partenaire, agent ;
- ce que l'appelant doit accomplir ;
- quelles données entrent et sortent ;
- ce que l'appelant ne doit jamais voir ;
- les exigences de latence, volume et fiabilité ;
- les contraintes de compatibilité et de versioning.
2. Modéliser les ressources et actions
- Utilisez des noms pour les ressources et des actions explicites pour les opérations qui ne sont pas du CRUD.
- Gardez les URL stables et prévisibles.
- Privilégiez une manière claire de faire une chose.
- Évitez de fuiter la structure de la base de données dans le contrat public.
- Définissez les identifiants, la propriété et la location.
3. Définir le schéma
Pour chaque endpoint ou interface :
- méthode et chemin ;
- objectif ;
- authentification et permissions ;
- paramètres de chemin, de requête et de corps ;
- règles de validation ;
- réponse en cas de succès ;
- réponses d'erreur ;
- idempotence ;
- pagination ;
- limites de débit ;
- exemples.
4. Concevoir les erreurs
Chaque erreur doit inclure :
- un code stable lisible par machine ;
- un message lisible par un humain ;
- le champ ou paramètre à l'origine de l'erreur ;
- un identifiant de requête pour le support ;
- pas de traces de pile, secrets ou chemins internes.
Utilisez des codes de statut HTTP cohérents. Ne renvoyez pas 200 pour une opération échouée.
5. Sécurité et vie privée
- Authentifiez chaque endpoint non public.
- Autorisez au niveau de l'objet, pas seulement au niveau de la route.
- Validez toute entrée à la frontière.
- Renvoyez uniquement les champs dont l'appelant a besoin.
- N'exposez pas les identifiants internes s'ils divulguent des informations.
- Définissez les limites de débit et les contrôles anti-abus.
- Traitez les webhooks comme des entrées non fiables.
6. Évolutivité
- Ajoutez des champs plutôt que de modifier leur signification.
- Conservez les anciens champs jusqu'à ce que les clients migrent.
- Ne versionnez que lorsque c'est nécessaire.
- Documentez la dépréciation et la migration.
- Évitez les changements cassants dans les versions mineures.
7. Format de sortie
## Contrat
### `METHOD /path`
**Objectif :** <ce qu'il fait>
**Authentification :** <qui peut l'appeler>
**Idempotence :** <oui/non et clé>
#### Requête
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
#### Réponse
```json
{}
```
#### Erreurs
| Statut | Code | Quand |
|---|---|---|
#### Exemple
```http
METHOD /path
...
```
## Compatibilité
- <ce qui peut changer>
- <ce qui nécessite une nouvelle version>
## Questions ouvertes
- <question>
Règles
- N'inventez pas de règles métier.
- N'exposez pas de champs internes sans raison.
- N'utilisez pas de nomenclature incohérente entre les endpoints.
- Ne concevez pas une API publique autour du schéma actuel de la base de données.
- N'omettez pas les comportements d'erreur et d'état vide.
- Si l'API gère de l'argent, de la santé ou des données personnelles, exigez une revue de sécurité.
Vérifications qualité
- L'appelant et le travail sont clairs.
- Le schéma est complet.
- Les erreurs sont cohérentes et sécurisées.
- L'authentification et les permissions au niveau objet sont définies.
- La pagination et les limites sont définies.
- La compatibilité est traitée.
- Les exemples sont valides.