La structuration des endpoints d’une API REST repose sur des conventions et des bonnes pratiques permettant d’assurer la clarté, la cohérence et la facilité d’utilisation pour les développeurs. Voici notre guide pour bien utiliser les verbes HTTP (GET, POST, PUT, DELETE) et nommer les URLs de manière optimale.

Utilisation des verbes HTTP

Les verbes HTTP sont au cœur des API REST et permettent d’indiquer l’action à effectuer sur une ressource. Voici comment nous les utilisons correctement :

• GET : Utilisé pour récupérer des informations sans modifier l’état du serveur. Exemple :
  • GET /users pour récupérer la liste des utilisateurs.
  • GET /users/{id} pour récupérer un utilisateur spécifique.
• POST : Utilisé pour créer une nouvelle ressource dont on ne connait pas l’id a priori. Exemple :
  • POST /users avec un corps de requête contenant les informations d’un nouvel utilisateur.
• PUT : Utilisé pour mettre à jour une ressource existante ou la créer avec un id spécifique si elle n’existe pas. Exemple :
  • PUT /users/{id} avec un corps de requête contenant les nouvelles informations de l’utilisateur.
• DELETE : Utilisé pour supprimer une ressource. Exemple :
  • DELETE /users/{id} pour supprimer un utilisateur spécifique.

Ces verbes doivent être associés aux bonnes opérations pour garantir une utilisation intuitive et cohérente de l’API.

Règles de nommage des URLs

Un autre aspect important de la conception des endpoints est le nommage des URLs. Voici les règles que nous suivons :

1. Utiliser des noms de ressources (noms d’objets) au pluriel :
   • Les endpoints doivent représenter des objets ou des collections d’objets. Exemple :
     • GET /products pour récupérer une liste de produits.
     • GET /products/{id} pour récupérer un produit spécifique.
2. Éviter les verbes dans les URLs :
   • Les verbes sont déjà exprimés par les méthodes HTTP. Il est donc inutile d’inclure des verbes comme « get » ou « delete » dans les chemins. Exemple :
     • Préférez GET /users à GET /getUsers.
3. Respecter la hiérarchie des ressources :
   • Lorsque des ressources sont imbriquées, structurer les URLs en reflétant cette relation. Exemple :
     • GET /users/{id}/orders pour récupérer les commandes d’un utilisateur spécifique.
4. Utiliser des identifiants clairs :
   • Privilégier des identifiants uniques pour représenter les ressources. Exemple :
     • GET /products/{sku} si le SKU est l’identifiant unique d’un produit.
5. Respecter la casse :
   • Utiliser des lettres minuscules et séparer les mots par des tirets. Exemple :
     • GET /product-categories plutôt que GET /ProductCategories ou GET /product_categories.

Bonnes pratiques supplémentaires

• Utilisons des codes HTTP appropriés : Retournons des codes comme 200 pour le succès, 201 pour une création, 404 pour une ressource introuvable, ou 500 en cas d’erreur serveur.
• Documentons nos endpoints : Assurons-nous de fournir une documentation claire et complète pour chaque endpoint.
• Versionnons nos APIs : Ajoutons une version dans l’URL pour permettre des mises à jour sans casser les applications existantes. Exemple :
  • GET /v1/users.

En respectant ces règles, nous garantissons une API REST claire, intuitive et facile à utiliser, ce qui améliore l’expérience des développeurs et la maintenabilité de notre application.