Noms de ressources API REST : singulier ou pluriel ?

En bref

Les noms de ressources des API REST doivent être au pluriel. Utilisez /pets/{id} et non /pet/{id}. Les noms au pluriel représentent les collections de manière cohérente, s'alignent avec la sémantique HTTP et correspondent à la façon dont les développeurs conçoivent les ressources. L'API Petstore moderne utilise des noms au pluriel dans toute sa conception, suivant les meilleures pratiques de l'industrie.

Introduction

Vous concevez une API REST. Vous avez besoin d'un point d'accès pour obtenir un utilisateur par ID. Utilisez-vous /user/123 ou /users/123 ? Cette question a suscité d'innombrables débats, fils de discussion Stack Overflow et disputes d'équipe.

La réponse est claire : utilisez le pluriel. Mais comprendre le pourquoi est plus important que de mémoriser la règle. Le raisonnement est lié au fonctionnement de REST, au comportement des collections et à la façon dont les développeurs conçoivent les ressources.

L'ancien Swagger Petstore s'est trompé à ce sujet, en utilisant /pet/{id} au lieu de /pets/{id}. Cette incohérence a enseigné à des millions de développeurs le mauvais modèle. L'API Petstore moderne corrige cela en utilisant des noms au pluriel de manière cohérente sur tous les points d'accès.

💡

Si vous construisez ou testez des API REST, Apidog vous aide à valider les conventions de nommage des ressources, à tester la cohérence des points d'accès et à garantir que votre API suit les meilleures pratiques REST. Vous pouvez importer des spécifications OpenAPI, vérifier les modèles de nommage et détecter les incohérences avant qu'elles n'atteignent la production.

bouton

Dans ce guide, vous apprendrez pourquoi les noms au pluriel sont le bon choix, comment ils s'alignent sur les principes REST et comment les implémenter correctement en utilisant l'API Petstore moderne comme référence.

Le débat Pluriel vs Singulier

Le débat existe parce que les deux approches semblent logiques à première vue.

L'argument du singulier

« Quand je demande /user/123, j'obtiens un seul utilisateur, pas plusieurs. Le singulier a du sens. »

Ce raisonnement se concentre sur la réponse : vous obtenez une seule ressource, donc l'URL doit être au singulier.

L'argument du pluriel

« L'URL représente une collection. /users est la collection de tous les utilisateurs. /users/123 est l'élément 123 de cette collection. »

Ce raisonnement se concentre sur la structure des ressources : les URL représentent des collections, et vous accédez à des éléments au sein de ces collections.

Pourquoi cela est important

Votre choix affecte :

Cohérence de l'API - Un nommage mixte embrouille les développeurs
Modèles mentaux - Comment les développeurs comprennent la structure de votre API
Génération de code - Les outils génèrent du code client basé sur les noms de ressources
Clarté de la documentation - La documentation doit expliquer votre logique de nommage

Pourquoi les noms au pluriel l'emportent

Les noms de ressources au pluriel s'alignent avec les principes REST et la sémantique HTTP. Voici pourquoi.

1. Les collections sont au pluriel

Dans REST, les ressources sont des collections. Lorsque vous accédez à /users, vous accédez à la collection d'utilisateurs. Lorsque vous accédez à /users/123, vous accédez à l'élément 123 de la collection d'utilisateurs.

GET /users          ← La collection d'utilisateurs
GET /users/123      ← Élément 123 de la collection d'utilisateurs
POST /users         ← Ajouter à la collection d'utilisateurs
DELETE /users/123   ← Supprimer l'élément 123 de la collection d'utilisateurs

Ce modèle mental est cohérent. La collection est toujours /users, que vous accédiez à tous les éléments ou à un seul.

Avec des noms singuliers, le modèle mental se brise :

GET /user           ← Quel utilisateur ?
GET /user/123       ← Cela a du sens
POST /user          ← Ajouter à... quoi ?

2. Les méthodes HTTP opèrent sur des collections

Les méthodes HTTP décrivent les opérations sur les collections :

GET /users - Récupérer la collection
POST /users - Ajouter à la collection
GET /users/123 - Récupérer l'élément 123 de la collection
PUT /users/123 - Remplacer l'élément 123 dans la collection
DELETE /users/123 - Supprimer l'élément 123 de la collection

La collection est la ressource. Les éléments individuels sont des membres de cette collection.

3. Cohérence entre les points d'accès

Les noms au pluriel créent de la cohérence :

GET /pets           ← Collection
GET /pets/123       ← Élément de la collection
GET /orders         ← Collection
GET /orders/456     ← Élément de la collection

Les noms singuliers vous obligent à passer du singulier au pluriel :

GET /pet            ← N'a pas de sens
GET /pet/123        ← Cela a du sens
GET /pets           ← Attendez, c'est au pluriel maintenant ?

4. Normes de l'industrie

Les API majeures utilisent des noms au pluriel :

API GitHub: /repos, /users, /issues
API Stripe: /customers, /charges, /subscriptions
API Twilio: /accounts, /messages, /calls
API Google: /users, /groups, /files

L'API Petstore moderne suit cette norme avec /pets, /orders, /users.

Le modèle mental de la collection

Comprendre les collections vous aide à concevoir de meilleures API.

Collections dans REST

Une collection est un ensemble de ressources. Dans une API de boutique d'animaux :

/pets - La collection de tous les animaux de compagnie
/orders - La collection de toutes les commandes
/users - La collection de tous les utilisateurs

Chaque collection prend en charge des opérations :

GET /pets           ← Lister les animaux de compagnie (avec filtrage, pagination)
POST /pets          ← Créer un nouvel animal de compagnie
GET /pets/{id}      ← Obtenir un animal de compagnie spécifique
PUT /pets/{id}      ← Mettre à jour un animal de compagnie spécifique
DELETE /pets/{id}   ← Supprimer un animal de compagnie spécifique

Sous-collections

Les collections peuvent contenir des sous-collections :

GET /pets/{id}/photos           ← Collection de photos pour l'animal {id}
POST /pets/{id}/photos          ← Ajouter une photo à l'animal {id}
GET /pets/{id}/photos/{photoId} ← Photo spécifique

Le modèle reste cohérent : les collections sont au pluriel, les éléments sont accessibles par ID.

Exemple de l'API Petstore moderne

L'API Petstore moderne l'implémente correctement :

GET /pets
GET /pets/{petId}
GET /pets/{petId}/photos
POST /pets/{petId}/vaccinations
GET /orders
GET /orders/{orderId}
GET /orders/{orderId}/items

Chaque collection est au pluriel. Chaque accès à un élément utilise {id} au sein de cette collection.

Comment l'API Petstore moderne utilise les noms au pluriel

Voyons des exemples concrets de l'API Petstore moderne.

Ressources animales (Pets)

GET    /pets                    ← Lister tous les animaux de compagnie
POST   /pets                    ← Créer un nouvel animal de compagnie
GET    /pets/{petId}            ← Obtenir un animal de compagnie spécifique
PUT    /pets/{petId}            ← Mettre à jour un animal de compagnie
DELETE /pets/{petId}            ← Supprimer un animal de compagnie
GET    /pets?status=AVAILABLE   ← Filtrer les animaux de compagnie par statut

Ressources de commande (Orders)

GET    /orders                  ← Lister toutes les commandes
POST   /orders                  ← Créer une commande
GET    /orders/{orderId}        ← Obtenir une commande spécifique
PUT    /orders/{orderId}        ← Mettre à jour une commande
DELETE /orders/{orderId}        ← Annuler une commande

Ressources utilisateur (Users)

GET    /users                   ← Lister les utilisateurs
POST   /users                   ← Créer un utilisateur
GET    /users/{userId}          ← Obtenir un utilisateur spécifique
PUT    /users/{userId}          ← Mettre à jour un utilisateur
DELETE /users/{userId}          ← Supprimer un utilisateur

Ressources imbriquées

GET /pets/{petId}/photos                    ← Photos de l'animal
POST /pets/{petId}/photos                   ← Ajouter une photo
GET /pets/{petId}/vaccinations              ← Vaccinations de l'animal
POST /pets/{petId}/vaccinations             ← Enregistrer une vaccination
GET /orders/{orderId}/items                 ← Articles de la commande

Consultez la documentation complète de l'API REST pour une liste complète des points d'accès.

Arguments courants en faveur du singulier (et pourquoi ils sont erronés)

Examinons les arguments courants en faveur des noms singuliers.

Argument 1 : « La réponse est singulière »

Affirmation : « Quand je fais un GET /user/123, j'obtiens un seul utilisateur. Le singulier a du sens. »

Contre-argument : L'URL représente l'emplacement de la ressource, pas la réponse. /users/123 signifie « l'élément 123 de la collection d'utilisateurs ». Le fait que la réponse soit singulière ne change pas la structure de la collection.

Argument 2 : « C'est plus lisible dans le code »

Affirmation : « getUser(id) est plus lisible que getUsers(id). »

Contre-argument : Le nommage de votre code client est indépendant de la structure de l'URL. Vous pouvez avoir :

// URL: GET /users/123
function getUser(id) {
  return api.get(`/users/${id}`);
}

Le nom de la fonction n'a pas besoin de correspondre à l'URL.

Argument 3 : « Le singulier évite les problèmes de grammaire »

Affirmation : « Qu'en est-il des ressources comme "status" ou "information" qui n'ont pas de pluriels clairs ? »

Contre-argument : Ce sont généralement des ressources singleton, pas des collections. Utilisez le singulier pour les singletons :

GET /status         ← Statut du système (singleton)
GET /configuration  ← Configuration de l'application (singleton)
GET /users          ← Collection d'utilisateurs (pluriel)

Argument 4 : « Mon ORM utilise des noms de table au singulier »

Affirmation : « Mes tables de base de données sont au singulier (user, order), donc mon API devrait correspondre. »

Contre-argument : La conception de votre API ne devrait pas divulguer les détails d'implémentation de la base de données. Les API REST représentent des ressources, pas des tables de base de données. Utilisez le pluriel pour les collections quel que soit votre schéma de base de données.

Test du nommage des ressources avec Apidog

Apidog vous aide à valider et tester les conventions de nommage des ressources.

Importer l'API Petstore moderne

Importez la spécification OpenAPI de l'API Petstore moderne
Apidog détecte automatiquement les modèles de ressources
Vérifiez la cohérence du nommage des points d'accès

Créer des tests de conventions de nommage

// Script de test Apidog
pm.test("Resource names are plural", function() {
  const path = pm.request.url.getPath();
  const segments = path.split('/').filter(s => s);

  // Vérifier que le premier segment est au pluriel
  const resource = segments[0];
  pm.expect(resource).to.match(/s$/); // Se termine par 's'
});

Valider la cohérence

Apidog peut vérifier :

Tous les points d'accès de collection utilisent des noms au pluriel
Les sous-ressources suivent le même modèle
Pas de mélange de singulier/pluriel dans la même API

Tester avec des requêtes réelles

GET https://api.petstoreapi.com/v1/pets
GET https://api.petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24
GET https://api.petstoreapi.com/v1/orders

Apidog valide les réponses et vous aide à assurer la cohérence de nommage sur l'ensemble de votre API.

Cas limites et exceptions

Certaines ressources ne correspondent pas au modèle du pluriel.

Ressources singleton

Les ressources qui n'existent qu'une seule fois doivent être au singulier :

GET /status         ← Statut du système
GET /configuration  ← Configuration de l'application
GET /health         ← Vérification de l'état de santé
GET /metrics        ← Métriques du système

Ce ne sont pas des collections, donc le pluriel ne s'applique pas.

Ressources contrôleur

Actions qui ne correspondent pas aux opérations CRUD :

POST /login         ← Action d'authentification
POST /logout        ← Fin de session
POST /search        ← Opération de recherche complexe

Ce sont des exceptions acceptables car elles représentent des actions, pas des ressources.

Noms indénombrables

Certains noms n'ont pas de pluriel clair :

GET /information    ← Singulier (indénombrable)
GET /data           ← Singulier (indénombrable)
GET /equipment      ← Singulier (indénombrable)

Utilisez le singulier pour les noms indénombrables, mais ceux-ci sont rares dans les API typiques.

Approche de l'API Petstore moderne

L'API Petstore moderne gère ces cas :

# Collections (pluriel)
GET /pets
GET /orders
GET /users

# Singletons (singulier)
GET /health
GET /metrics

# Actions (verbes singuliers)
POST /login
POST /logout

Conclusion

Les noms de ressources des API REST doivent être au pluriel. Cela s'aligne avec la sémantique des collections, les méthodes HTTP et les normes de l'industrie. L'API Petstore moderne démontre ce modèle correctement sur tous les points d'accès.

Points clés à retenir :

Utilisez des noms au pluriel pour les collections (/pets, /orders, /users)
Les éléments individuels sont accessibles au sein des collections (/pets/123)
Les ressources singleton peuvent être au singulier (/status, /health)
La cohérence est plus importante que la perfection
Testez vos conventions de nommage avec Apidog

Le débat pluriel vs singulier est réglé. Suivez la norme de l'industrie, utilisez des noms au pluriel et construisez des API que les développeurs comprennent intuitivement.

Prochaines étapes :

Vérifiez la cohérence du nommage de vos points d'accès API
Consultez la documentation de l'API Petstore moderne pour des modèles de référence
Utilisez Apidog pour valider la conception de votre API
Mettez à jour votre spécification OpenAPI avec des noms de ressources au pluriel

Foire aux questions

Devrais-je modifier mon API existante du singulier au pluriel ?

Si votre API est déjà en production, modifier les noms de ressources est un changement cassant. Considérez :

L'ajout de nouveaux points d'accès v2 avec des noms au pluriel
Le maintien de la compatibilité ascendante avec des redirections
La documentation claire de la convention de nommage

Ne cassez pas les clients existants pour la seule cohérence de nommage.

Qu'en est-il des ressources déjà au pluriel ?

Si le nom de la ressource est naturellement au pluriel (comme « analytics » ou « series »), gardez-le tel quel :

GET /analytics      ← Déjà au pluriel
GET /series         ← Déjà au pluriel
GET /species        ← Déjà au pluriel

Comment gérer les ressources imbriquées ?

Gardez les deux niveaux au pluriel :

GET /users/{userId}/orders              ← Les deux au pluriel
GET /pets/{petId}/vaccinations          ← Les deux au pluriel
GET /orders/{orderId}/items             ← Les deux au pluriel

Et si mon équipe préfère le singulier ?

La cohérence au sein de votre API est ce qui compte le plus. Si votre équipe a déjà standardisé les noms singuliers et que changer créerait de la confusion, restez au singulier. Mais pour les nouvelles API, utilisez le pluriel.

GraphQL utilise-t-il le pluriel ou le singulier ?

GraphQL utilise généralement le singulier pour les requêtes d'éléments uniques et le pluriel pour les listes :

query {
  user(id: "123") { ... }      # Singulier
  users(limit: 10) { ... }     # Pluriel
}

C'est différent de REST car les requêtes GraphQL sont explicites quant au retour d'un élément ou de plusieurs.

Comment l'API Petstore moderne gère-t-elle cela ?

L'API Petstore moderne utilise des noms au pluriel de manière cohérente sur tous les points d'accès REST. Consultez le guide de l'API REST pour des exemples complets.

Puis-je tester les conventions de nommage automatiquement ?

Oui, Apidog peut exécuter des tests automatisés pour vérifier les modèles de nommage des ressources sur l'ensemble de votre API. Importez votre spécification OpenAPI et créez des cas de test pour les conventions de nommage.

Qu'en est-il des API non-anglaises ?

La règle du pluriel s'applique quelle que soit la langue. Si votre API utilise des noms de ressources français, utilisez les pluriels français. Si elle utilise le japonais, suivez les règles de grammaire japonaise. Le principe (les collections sont au pluriel) reste le même.