10 règles concrètes pour mieux nommer une API REST
Ouvrez n'importe quelle base de code de plus de deux ans et vous y trouverez les cicatrices : /getUser, /user_list, [REDACTED PATH] à côté deorder_id` dans la même réponse. Rien ne casse forcément, mais tout ralentit les équipes.
{% cta https://apidog.com/?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation %} Essayez Apidog aujourd'hui {% endcta %}
Le nommage est l'une des décisions de conception d'API les moins coûteuses à prendre et les plus difficiles à inverser. Une fois que des clients dépendent de /getOrders, vous devrez probablement le maintenir pendant des années.
Ce guide propose une règle pratique pour chaque décision de nommage courante dans une API REST, avec un exemple et un contre-exemple. Il complète les bonnes pratiques générales des API REST, en se concentrant sur le sujet qui provoque le plus de débats : comment nommer les choses.
1. Utilisez des noms pluriels pour les collections
Une URL identifie une ressource, pas une opération. Une collection est un ensemble de ressources : utilisez donc un nom pluriel.
http
GET /v1/products
GET /v1/products/89
GET /v1/orders
À éviter :
http
GET /v1/getProducts
GET /v1/product
GET /v1/productList
/products désigne la collection et /products/89, le produit 89 dans cette collection. La forme plurielle reste cohérente aux deux niveaux.
L'exception concerne les ressources singleton :
http
GET /v1[REDACTED PATH]
Si un utilisateur ne possède qu'un seul panier, /cart peut rester au singulier.
Les directives API REST de Microsoft recommandent également cette approche, suivie par de nombreuses API publiques comme Stripe, GitHub et Shopify.
2. Évitez les verbes dans les chemins
La méthode HTTP porte déjà le verbe. Ajouter un second verbe dans le chemin duplique l'information et éloigne l'API du modèle de ressource.
http
GET /v1/orders/42
DELETE /v1/orders/42
PATCH /v1/orders/42
À éviter :
http
GET /v1/fetchOrder/42
POST /v1/deleteOrder/42
POST /v1/updateOrderStatus
Un chemin unique facilite aussi la documentation, les tests, la mise en cache et l'invalidation. Un CDN peut relier GET /v1/orders/42 à DELETE /v1/orders/42, mais pas nécessairement /fetchOrder/42 à /deleteOrder/42.
3. Utilisez le kebab-case dans les chemins
Pour les segments composés de plusieurs mots, séparez les mots avec des tirets.
http
/v1/gift-cards
/v1/shipping-addresses
À éviter :
http
/v1/giftCards
/v1/gift_cards
/v1/GiftCards
Les tirets sont interprétés comme des séparateurs de mots par les moteurs de recherche. Les underscores peuvent disparaître dans les liens soulignés, et le camelCase favorise les erreurs de casse :
http
/giftCards
/giftcards
Ces deux URL sont différentes sur la plupart des serveurs. Les directives REST de Zalando en font une règle obligatoire.
4. Choisissez une seule casse pour le JSON
Pour les champs des requêtes et des réponses, camelCase et snake_case sont tous deux valides. Ce qui pose problème, c'est de les mélanger.
Choisissez une convention et appliquez-la partout :
json
{
"orderId": 42,
"createdAt": "2026-08-30T09:15:00Z",
"totalAmount": 4999
}
Ou :
json
{
"order_id": 42,
"created_at": "2026-08-30T09:15:00Z",
"total_amount": 4999
}
À éviter :
json
{
"orderId": 42,
"created_at": "2026-08-30T09:15:00Z",
"TotalAmount": 4999
}
Le camelCase s'intègre bien aux clients JavaScript et Java. Le snake_case est souvent plus lisible et correspond à Python, Ruby et aux colonnes SQL ; Stripe l'utilise partout.
Documentez votre choix dans le guide de style et dans les schémas. La casse mixte est généralement un problème de gouvernance, pas une question de goût.
5. Limitez l'imbrication à deux niveaux
L'imbrication exprime la propriété :
http
GET /v1[REDACTED PATH]
Cette URL signifie « les commandes appartenant à l'utilisateur 42 ». Au-delà de deux niveaux, elle devient difficile à utiliser.
Préférez :
http
GET /v1[REDACTED PATH]
GET /v1/orders/1337/refunds
À éviter :
http
GET /v1[REDACTED PATH]7/status
Une URL profondément imbriquée oblige le client à transmettre tous les identifiants ancêtres, même lorsque la ressource feuille possède son propre identifiant global.
Règle pratique : si une URL contient au moins trois identifiants, aplatissez-la. Une fois la commande identifiée, /orders/1337 suffit.
6. Placez les filtres, le tri et la pagination dans les paramètres
Les chemins identifient les ressources. Les paramètres de requête modifient la manière dont vous les consultez.
http
GET /v1/orders?status=active&sort=-created_at&limit=50&cursor=eyJpZCI6NDJ9
GET /v1/products?category=electronics&min_price=1000
À éviter :
http
GET /v1/orders/active
GET /v1/orders/sorted-by-date-desc
GET /v1/getOrdersByStatusAndDate
Le format sort=-created_at utilise le préfixe - pour indiquer un tri descendant et évite d'ajouter un paramètre order=desc.
Les chemins comme /orders/active semblent simples, mais chaque combinaison de filtres finit par créer un nouveau point d'API. Choisissez aussi une convention de pagination — par exemple limit/cursor ou page/per_page — et réutilisez-la partout.
Consultez ce guide de pagination d'API pour comparer la pagination par curseur et par offset.
7. Versionnez l'API dans le chemin
Deux approches sont courantes :
http
/v1/products
Ou via un en-tête :
http
Accept: application/vnd.myapi.v1+json
Le versionnement par en-tête est plus proche d'une conception REST « pure », car l'URL continue d'identifier la même ressource. Les directives de conception d'API de Google reconnaissent les deux approches.
En pratique, le versionnement dans le chemin est souvent plus opérationnel :
- la version apparaît dans les journaux ;
- elle est testable depuis un navigateur ;
- elle est facilement mise en cache ;
- le client ne peut pas oublier de fournir l'en-tête.
Utilisez une version majeure uniquement :
http
/v1/products
Évitez :
http
/v1.2/products
Les changements mineurs doivent rester additifs et non cassants. Pour comparer les différentes stratégies, consultez cette comparaison du versionnement d'API.
8. Traitez les identifiants comme opaques
Des identifiants séquentiels exposés publiquement donnent des informations sur le volume de données et facilitent l'énumération :
http
/orders/41
/orders/42
/orders/43
Ils peuvent aussi aggraver les failles d'autorisation au niveau objet, classées parmi les principaux risques du Top 10 de la sécurité des API de l'OWASP.
Préférez des identifiants opaques :
http
GET /v1/orders/ord_9f8e2a71b3
GET /v1[REDACTED PATH]-e29b-41d4-a716-446655440000
À éviter lorsque l'énumération est un risque :
http
GET /v1/orders/42
GET /v1/invoices/10883
Les identifiants aléatoires préfixés, comme ceux de Stripe (ord_9f8e2a71b3), sont lisibles dans les journaux et difficiles à deviner. Les contrôles d'autorisation restent indispensables : les identifiants opaques réduisent l'impact d'une erreur, mais ne la corrigent pas.
Vous pouvez conserver des clés entières en interne. Cette règle concerne uniquement les identifiants exposés dans l'API.
9. Modélisez les actions non-CRUD comme des contrôleurs
Certaines actions ne correspondent pas directement à une opération CRUD : annuler une commande, relancer un paiement ou renvoyer un e-mail.
Utilisez un point d'API de contrôleur :
http
POST /v1/orders/42/cancel
POST /v1/payments/pay_88a1/retry
À éviter :
`http
PATCH /v1/orders/42
{ "status": "cancelled" }
POST /v1/cancelOrder
{ "orderId": 42 }
`
C'est l'exception à la règle « pas de verbes dans les chemins ». Le verbe doit être placé à la fin, sous la ressource concernée, et l'action doit utiliser POST.
Une annulation peut déclencher un remboursement, libérer du stock et envoyer des notifications. La représenter comme une simple modification de champ oblige le serveur à déduire l'intention à partir du payload.
Un endpoint /cancel permet au contraire :
- d'attribuer des permissions spécifiques ;
- de conserver une piste d'audit claire ;
- d'ajouter des paramètres dédiés, comme une raison d'annulation.
10. Gardez une casse cohérente pour les en-têtes et les paramètres
Les en-têtes personnalisés doivent utiliser le format Hyphenated-Pascal-Case :
http
Idempotency-Key: abc123
[REDACTED IDENTIFIER]
Évitez l'ancien préfixe X-, déprécié par le RFC 6648 en 2012. Les noms d'en-tête sont insensibles à la casse sur le réseau, mais la documentation et les SDK doivent les écrire de manière uniforme.
Les paramètres de requête doivent suivre la convention de votre JSON. Si vos corps utilisent le snake_case :
http
GET /v1/orders?min_price=1000&created_after=2026-01-01
Évitez de mélanger les conventions :
http
GET /v1/orders?minPrice=1000
Un développeur qui lit created_at dans une réponse et doit utiliser createdAfter dans une requête fera probablement une erreur — et les suivants aussi.
Les 10 règles en un coup d'œil
| # | Règle | Faites | Ne faites pas |
|---|---|---|---|
| 1 | Noms pluriels pour les collections |
/products, /products/89
|
/getProducts, /productList
|
| 2 | Pas de verbes dans les chemins | DELETE /orders/42 |
POST /deleteOrder/42 |
| 3 | Segments en kebab-case | /gift-cards |
/giftCards, /gift_cards
|
| 4 | Une seule casse JSON |
order_id partout |
Mélanger orderId et order_id
|
| 5 | Deux niveaux d'imbrication maximum | /orders/1337/refunds |
`[REDACTED PATH] |
| 6 | Filtres et pagination dans les paramètres | ?status=active&sort=-created_at |
/orders/active |
| 7 | Version majeure dans le chemin | /v1/products |
/v1.2/products |
| 8 | Identifiants opaques | /orders/ord_9f8e2a71b3 |
/orders/42 exposé publiquement |
| 9 | Contrôleurs pour les actions | POST /orders/42/cancel |
PATCH avec {"status":"cancelled"}
|
| 10 | Casse cohérente |
Idempotency-Key, ?min_price=
|
X-IDEMPOTENCY_KEY, ?minPrice=
|
Appliquer ces conventions à grande échelle
Un guide de style dans un wiki ne suffit pas. Les équipes qui maintiennent des API cohérentes conçoivent d'abord les endpoints et appliquent les conventions avant que le code n'existe : c'est le principe de la gouvernance d'API.
Avec Apidog, vous pouvez définir les endpoints dans un concepteur visuel basé sur les schémas. Le chemin, la casse et les paramètres deviennent des artefacts de conception explicites plutôt que des chaînes cachées dans les contrôleurs.
Les composants partagés permettent de définir une seule fois les schémas Pagination, Error et Money, puis de les réutiliser dans toute l'API. Vous évitez ainsi de réinventer per_page sous le nom pageSize dans un nouveau service.
Grâce aux espaces de travail d'équipe et à la révision intégrée, un responsable peut repérer /getUserOrders au stade de la conception, lorsque le changement est encore simple. La spécification peut ensuite piloter la documentation, les serveurs de mock et les tests.
Découvrez Apidog et essayez-le gratuitement sur votre prochain endpoint. Moderniser une API existante est difficile ; appliquer de bonnes conventions aux nouvelles API l'est beaucoup moins.
FAQ
Les URL REST doivent-elles être au pluriel ou au singulier ?
Utilisez le pluriel pour toute ressource pouvant avoir plusieurs instances :
/products
/orders
/users
La forme plurielle reste naturelle pour la collection (/orders) comme pour un élément (/orders/42). Réservez le singulier aux vrais singletons, comme `[REDACTED PATH]
Pour approfondir la modélisation des ressources, consultez ce guide sur ce qu'est une API REST.
Le camelCase ou le snake_case est-il préférable pour les champs JSON ?
Aucun ne l'emporte systématiquement. Le camelCase convient aux consommateurs JavaScript, tandis que le snake_case est courant en Python, Ruby et dans l'API publique de Stripe.
La règle essentielle est d'en choisir un, de le documenter dans le guide de style et de le faire respecter lors de la validation des schémas. Une casse mixte entre les endpoints est plus problématique que le choix lui-même.
Dois-je mettre la version de l'API dans l'URL ou dans un en-tête ?
Utilisez le chemin, par exemple /v1/orders, sauf exigence forte en faveur de l'hypermedia. Les versions dans le chemin sont immédiatement visibles dans les journaux, les caches et les tests navigateur.
Le versionnement par en-tête conserve des URL stables, mais peut échouer silencieusement lorsqu'un client oublie l'en-tête. Utilisez uniquement des versions majeures et livrez les changements mineurs de manière additive et non cassante.
Les verbes sont-ils parfois acceptables dans un chemin REST ?
Oui, pour les endpoints de contrôleur qui représentent des actions non-CRUD :
http
POST /orders/42/cancel
POST /payments/pay_88a1/retry
Le verbe doit être placé à la fin du chemin, sous la ressource concernée, et la méthode doit être POST. Dans tous les autres cas, la méthode HTTP porte le verbe et le chemin reste composé de noms.
Top comments (0)