Révision de Conception d'API
Vue d'ensemble
Jugez une API du point de vue du client : noms prévisibles, codes de statut honnêtes, un format d'erreur unique, reprises sûres et aucun changement cassant surprise. Chaque constat pointe vers une route concrète et montre la conception corrigée.
Méthode
- Inventaire. Listez chaque endpoint sous la forme
METHODE /chemin → codes de statut → forme requête/réponse. Lisez les routes, contrôleurs, fichiers OpenAPI et DTOs. - Vérifiez chaque endpoint selon les règles ci-dessous.
- Vérifiez l'API dans son ensemble : la cohérence entre les endpoints est plus importante qu'un choix isolé.
- Modifications : si vous examinez un diff, comparez les contrats ancien et nouveau et signalez tout ce qui casse les clients existants.
- Rapportez en utilisant le contrat ci-dessous.
Règles
| Domaine | Règle |
|---|---|
| Ressources | Noms au pluriel, sans verbes : POST /commandes, pas /creerCommande. Imbriquez uniquement pour la possession réelle : /utilisateurs/{id}/commandes. |
| Méthodes | GET lit et est sûr. POST crée. PUT remplace. PATCH modifie partiellement. DELETE supprime. Ne changez jamais l'état avec GET. |
| Codes de statut | 200 OK, 201 Créé (+ Location), 204 Pas de contenu, 400 entrée invalide, 401 non authentifié, 403 non autorisé, 404 manquant, 409 conflit, 422 validation, 429 limité par débit, 5xx uniquement pour les erreurs serveur. Jamais 200 avec {"error": ...}. |
| Erreurs | Un seul format partout, par ex. RFC 9457 : { "type", "title", "status", "detail", "errors": [{ "field", "message" }] }. Pas de traces de pile ni de SQL dans les réponses. |
| Nommage | Une seule convention pour les champs JSON (camelCase ou snake_case), identifiants cohérents, horodatages ISO 8601 UTC, montants monétaires en unités mineures entières ou chaîne décimale avec devise. |
| Collections | Paginez chaque liste (curseur préféré pour les grandes données ou changeantes), limitez la taille de page, renvoyez le curseur suivant ou des liens. Filtrage et tri via des paramètres de requête. |
| Idempotence | Les POST répétés qui créent des paiements, commandes ou emails acceptent une Idempotency-Key. PUT et DELETE sont idempotents par conception. |
| Versioning | Une stratégie claire (chemin /v1 ou en-tête). Les changements cassants vont dans une nouvelle version. |
| Changements cassants | Supprimer ou renommer des champs, changer les types, rendre optionnel obligatoire, modifier les codes de statut ou le format d'erreur, renforcer la validation. |
| Sécurité | Authentification sur chaque route non publique, vérification de propriété au niveau objet, limites de débit sur les routes d'authentification et coûteuses, pas de données sensibles dans les URLs. |
| Performance | Pas de réponses sans limite, support du paramètre fields ou des réponses allégées pour les objets lourds, ETag ou Cache-Control pour les GET cachable. |
Contrat de sortie
Commencez par : N endpoints examinés, M constats (X cassants). Ensuite, par ordre d'impact décroissant :
### [Cassant | Élevé | Moyen | Faible] Titre
- Endpoint : METHODE /chemin (fichier:ligne)
- Problème : ce que le client rencontre
- Correctif : la route, le code de statut ou la forme JSON corrigés
Terminez par un court Résumé de cohérence (casse, format d'erreur, pagination, versioning : cohérent ou non) et, lors d'une conception de zéro, le tableau d'endpoints proposé.
Erreurs courantes
- Examiner les endpoints un par un et ne pas remarquer que deux d'entre eux divergent sur la casse ou le format d'erreur.
- Recommander une refonte alors qu'un ajout rétrocompatible suffirait.
- Qualifier un changement de sûr parce que le code serveur fonctionne encore : vérifiez ce que les clients existants envoient et attendent.
- Utiliser 500 pour des erreurs de validation ou 404 pour des échecs d'autorisation sans décision délibérée.
Creado por Wageesha Tripathi · LinkedIn · Email · Plus de compétences