Nommer les ressources, pas les actions
Les URLs REST doivent decrire des objets. Commencez par des noms qui correspondent au domaine : `/users`, `/devices`, `/orders`.
Les actions sont portees par les verbes HTTP. `DELETE /orders/987` est plus clair que `/orders/987/cancel`.
Pluriel ou singulier, mais coherent
Le plus courant est le pluriel pour les collections (`/users`) et l'identifiant pour l'item (`/users/123`).
Le choix importe moins que la coherence. Appliquez la meme convention partout.
Hierarchies courtes
Les chemins imbriques expriment les relations (`/users/123/orders`). C'est utile si la ressource depend du parent.
Evitez les profondeurs excessives. Plus de deux niveaux cree du couplage et complique l'evolution.
Query params pour filtrer
Filtrage, tri et pagination passent par les query params : `/orders?status=paid&sort=-created_at&page=2`.
Le chemin reste centre sur l'identite, et vous pouvez ajouter des filtres sans casser les clients.
Choisir une convention de casse
Adoptez une casse unique. Le kebab-case est lisible en URL. Les query params sont souvent en snake_case.
Une convention stable permet aux clients de deviner les endpoints plus vite.
Concevoir pour l'evolution
Votre API va changer. Evitez d'inclure des details techniques internes dans les URLs.
Utilisez des noms metier, plus stables que les noms de tables ou de services.
Exemples qui tiennent dans le temps
Un design propre : `/devices`, `/devices/{id}`, `/devices/{id}/state`, `/alerts`. Chaque endpoint represente un objet clair.
En ajoutant des features, gardez les memes patterns. La coherence inspire confiance.