aj-geddes/rest-api-design

Que fait rest-api-design ?

Concevez des API RESTful en suivant les bonnes pratiques pour la modélisation des ressources, les méthodes HTTP, les codes d'état, le versioning et la documentation. Utilisez-le lors de la création de nouvelles API, de la conception de points de terminaison ou de l'amélioration de l'architecture API existante.

Principes fondamentaux

• Modélisation des ressources : Nommez les ressources avec des noms (pluriels) et utilisez des identifiants uniques (par exemple /utilisateurs, /utilisateurs/{id}).
• Méthodes HTTP : Utilisez les verbes standards : GET pour lire, POST pour créer, PUT/PATCH pour mettre à jour, DELETE pour supprimer.
• Codes d'état : Renvoyez les codes appropriés : 200 pour succès, 201 pour création, 204 pour suppression réussie, 400 pour erreur client, 404 pour ressource non trouvée, 500 pour erreur serveur.
• Versioning : Gérez les versions via l'URI (par exemple /v1/utilisateurs) ou l'en-tête Accept. Évitez les ruptures de compatibilité.
• Documentation : Documentez chaque endpoint avec OpenAPI / Swagger, en précisant les paramètres, les réponses et les exemples.

Bonnes pratiques supplémentaires

• Utilisez des requêtes paramétrées pour le filtrage, le tri et la pagination (par exemple ?page=1&limit=20&tri=nom).
• Gérez les erreurs de manière uniforme avec un format JSON standard (par exemple {"erreur": "message", "code": 400}).
• Implémentez l'authentification et l'autorisation via des jetons (OAuth2, JWT).
• Limitez les taux de requêtes avec des en-têtes RateLimit-*.
• Supportez la négociation de contenu via Content-Type et Accept.

Exemples de structure d'API

GET    /v1/utilisateurs          # Liste des utilisateurs
POST   /v1/utilisateurs          # Créer un utilisateur
GET    /v1/utilisateurs/{id}     # Lire un utilisateur
PUT    /v1/utilisateurs/{id}     # Mettre à jour un utilisateur
DELETE /v1/utilisateurs/{id}     # Supprimer un utilisateur

Ressources

• OpenAPI Specification
• REST API Tutorial
• HTTP Status Codes