Que fait api-design-principles ?
Maîtrisez les principes de conception d'API REST et GraphQL pour créer des API intuitives, évolutives et maintenables qui raviront les développeurs. Utilisez-le lors de la conception de nouvelles API, de la révision de spécifications d'API ou de l'établissement de normes de conception d'API.
Principes de base
- Suivez une approche orientée ressource : modélisez votre API autour de ressources (objets métier) plutôt que d'actions. Utilisez des noms pour les ressources, des verbes HTTP pour les actions (GET, POST, PUT, DELETE, PATCH).
- Utilisez des noms en anglais au pluriel :
/users,/orders,/products. Évitez les verbes dans les chemins d'URL. - Versionnez votre API : utilisez des en-têtes ou des chemins (par exemple,
/v1/) pour gérer les changements sans casser les clients existants. - Fournissez des messages d'erreur cohérents : utilisez une structure uniforme (par exemple,
{"error": {"code": "not_found", "message": "Ressource non trouvée"}}) avec des codes d'état HTTP appropriés (200, 201, 400, 401, 403, 404, 500). - Utilisez l'authentification et les autorisations : standardisez avec OAuth 2.0 ou JWT, et documentez les portées requises.
- Implémentez la pagination : pour les listes de ressources, utilisez le curseur ou la pagination basée sur la page avec des champs
next,prevettotal. - Utilisez les en-têtes de mise en cache :
ETag,If-None-Match,Cache-Controlpour améliorer les performances et réduire la charge serveur. - Documentez avec OpenAPI (Swagger) : générez une spécification lisible pour le développement client et les tests.
GraphQL
- Définissez un schéma clair : utilisez le langage de définition de schéma (SDL) pour décrire les types, requêtes et mutations.
- Évitez de sur-exposer les données : suivez le principe de moindre privilège ; ne renvoyez que ce qui est nécessaire.
- Utilisez le traitement par lot (DataLoader) : pour éviter le problème N+1 et optimiser la récupération de données.
- Gérez les erreurs dans le schéma : définissez des types d'erreur (par exemple,
UserError) et retournez-les dans la réponse. - Versionnez avec rupture minime : utilisez des dépréciations et des changements progressifs ; préférez l'ajout de nouveaux champs au changement de champs existants.