Convention de nommage API REST

Pour garder une cohérence et une bonne lisibilité dans vos APIs REST, nous vous recommandons fortement de suivre les conventions API REST.

Utiliser des bons noms de ressources

Votre API manipulera des ressources ou des collections. Utilisez donc des noms de ressources au pluriel dans vos URLs.

GET /api/publique/utilisateurs (fetch all)
GET /api/publique/utilisateurs/:id (fetch single)
POST /api/publique/utilisateurs (create single)

Vous ne devez pas inclure d'actions dans vos URLs. Par exemple, n'utilisez pas /api/utilisateurs/getAll ou /api/utilisateurs/create, à la place, utilisez les verbes HTTP appropriés.

Votre API doit être intuitive et facile à comprendre. Utilisez des noms de ressources clairs et descriptifs qui reflètent le contenu ou la fonction de la ressource. Evitez les abréviations ou les termes ambigus (data, info, contenu, etc.).

Utiliser les bons verbes HTTP

Utilisez les verbes HTTP standards pour indiquer l'action à effectuer sur la ressource.

• GET : Récupérer une ou plusieurs ressources
• POST : Créer une nouvelle ressource
• PATCH : Mettre à jour une ressource existante
• DELETE : Supprimer une ressource ...

Sous ressources

Pour représenter des relations entre ressources, utilisez des sous-ressources dans vos URLs.

GET /api/publique/utilisateurs/:id/commandes (fetch all orders for a user)

info

Dans ce cas, il n'est pas nécessaire de demander des modifications sur la configuration Kong. Si la route parente est déjà configurée, la sous-ressource sera automatiquement accessible.

Attention cependant à ne pas imbriquer trop profondément les sous-ressources. Limitez-vous à deux ou trois niveaux maximum pour garder des URLs lisibles et maintenables.

Nommer en minuscule et avec des tirets

Utilisez des lettres minuscules et des tirets (-) pour séparer les mots dans vos URLs. Eviter les majuscules, les espaces ou les underscores (_).

Versionning

Ajoutez la version de l'API dans l'URL, juste après /api/. Par exemple, pour la version 1:

GET /api/v1/publique/utilisateurs (fetch all)

Renvoyer les bons codes HTTP

Utilisez les codes de statut HTTP appropriés pour indiquer le résultat des opérations. Voici quelques exemples courants :

Code	Signification
200	OK - La requête a réussi
201	Created - La ressource a été créée avec succès
400	Bad Request - La requête est mal formée ou invalide
401	Unauthorized - Authentification requise ou invalide
403	Forbidden - Accès refusé
404	Not Found - Ressource non trouvée
418	I'm a teapot - Utilisé pour indiquer que le serveur est une théière (RFC 2324)