Pourquoi éviter les verbes dans les URLs d'API REST ?

En bref

Les URL d'API REST doivent contenir des noms (ressources), et non des verbes (actions). Les méthodes HTTP (GET, POST, PUT, DELETE) sont les verbes. L'utilisation de verbes d'action comme /getUser ou /createOrder viole les principes REST, crée des incohérences et rend les API plus difficiles à maintenir. La PetstoreAPI moderne utilise des URL axées sur les ressources de manière cohérente.

Introduction

Vous concevez un endpoint d'API pour rechercher des animaux par statut. Votre premier réflexe pourrait être : GET /findPetsByStatus?status=available. C'est descriptif, clair et indique exactement ce qu'il fait. C'est aussi incorrect.

Les API REST doivent utiliser des noms dans les URL, pas des verbes. La méthode HTTP est le verbe. GET /pets?status=available est la conception correcte. L'URL représente la ressource (animaux), et la méthode représente l'action (obtenir).

L'ancienne Swagger Petstore a commis cette erreur avec des endpoints comme /pet/findByStatus et /pet/findByTags. Ces verbes d'action dans les URL violent les principes REST et créent des problèmes de maintenance. La PetstoreAPI moderne corrige cela en utilisant des URL axées sur les ressources de manière cohérente.

Dans ce guide, vous apprendrez pourquoi les verbes n'ont pas leur place dans les URL REST, comment concevoir des endpoints axés sur les ressources et comment la PetstoreAPI moderne met cela en œuvre correctement.

Le problème des verbes dans les API REST

Les verbes d'action dans les URL indiquent que vous pensez en termes d'appels de procédure distante (RPC), et non en termes REST.

URL de style RPC (Incorrect)

POST /createUser
GET /getUser?id=123
PUT /updateUser
DELETE /deleteUser?id=123
GET /findUsersByRole?role=admin
POST /sendEmail
GET /calculateTotal

Ces URL décrivent des actions. Elles se lisent comme des appels de fonction : createUser(), getUser(), sendEmail().

URL de style REST (Correct)

POST /users
GET /users/123
PUT /users/123
DELETE /users/123
GET /users?role=admin
POST /emails
GET /orders/123/total

Ces URL décrivent des ressources. La méthode HTTP fournit l'action.

Pourquoi c'est important

Cohérence : Les URL REST suivent un schéma prévisible. Une fois que vous connaissez le nom de la ressource, vous connaissez tous les endpoints :

• GET /pets - Lister les animaux
• POST /pets - Créer un animal
• GET /pets/{id} - Obtenir un animal
• PUT /pets/{id} - Mettre à jour un animal
• DELETE /pets/{id} - Supprimer un animal

Avec les URL basées sur les verbes, chaque endpoint est unique. Il n'y a pas de modèle à suivre.

Scalabilité : À mesure que votre API grandit, les URL basées sur les verbes se multiplient :

• /findPetsByStatus
• /findPetsByTags
• /findPetsByOwner
• /findPetsByBreed
• /searchPets
• /queryPets

Les URL axées sur les ressources utilisent des paramètres de requête :

• GET /pets?status=available
• GET /pets?tags=friendly
• GET /pets?owner=john
• GET /pets?breed=labrador

Un seul endpoint gère tous les filtres.

Pourquoi les méthodes HTTP sont les verbes

REST tire parti des verbes intégrés de HTTP. Vous n'avez pas besoin d'inventer les vôtres.

Les méthodes HTTP correspondent aux opérations CRUD

POST   → Créer
GET    → Lire
PUT    → Mettre à jour (remplacer)
PATCH  → Mettre à jour (partiel)
DELETE → Supprimer

Ces méthodes ont des sémantiques définies. GET est sûr et idempotent. POST crée des ressources. DELETE les supprime.

Exemple : Gestion des utilisateurs

Incorrect (verbes dans les URL) :

POST /createUser
GET /getUser?id=123
POST /updateUser
POST /deleteUser

Chaque opération utilise une URL différente. La méthode HTTP ne transmet pas de sens.

Correct (méthodes HTTP comme verbes) :

POST /users           ← Créer un utilisateur
GET /users/123        ← Obtenir un utilisateur
PUT /users/123        ← Mettre à jour un utilisateur
DELETE /users/123     ← Supprimer un utilisateur

L'URL reste la même. La méthode change.

Avantages de l'utilisation des méthodes HTTP

1. Mise en cache : Les requêtes GET peuvent être mises en cache. Les navigateurs et les proxys le savent. Si vous utilisez POST /getUser, la mise en cache est rompue.

2. Idempotence : PUT et DELETE sont idempotents. Les appeler plusieurs fois a le même effet que de les appeler une seule fois. C'est important pour la logique de réessai.

3. Sécurité : GET est sûr – il ne modifie pas l'état. Les outils et les robots d'exploration peuvent appeler en toute sécurité les endpoints GET.

4. Conformité aux normes : Les clients HTTP, les proxys et les caches comprennent les méthodes HTTP. Ils ne comprennent pas vos verbes personnalisés.

Exemples réels de Swagger Petstore

L'ancienne Swagger Petstore inclut plusieurs endpoints basés sur des verbes.

Exemple 1 : Recherche d'animaux par statut

Swagger Petstore (Incorrect) :

GET /pet/findByStatus?status=available

Problèmes :

• findByStatus est une phrase verbale
• Incohérent avec l'endpoint /pet/{id}
• Ne peut pas être facilement étendu (qu'en est-il de la recherche par d'autres critères ?)

PetstoreAPI moderne (Correct) :

GET /pets?status=AVAILABLE

Avantages :

• Axé sur les ressources (/pets)
• Utilise des paramètres de requête pour le filtrage
• Cohérent avec les autres endpoints
• Facile à étendre : GET /pets?status=AVAILABLE&species=dog

Consultez la documentation REST de la PetstoreAPI moderne pour l'implémentation complète.

Exemple 2 : Recherche d'animaux par tags

Swagger Petstore (Incorrect) :

GET /pet/findByTags?tags=tag1,tag2

PetstoreAPI moderne (Correct) :

GET /pets?tags=friendly,trained

Exemple 3 : Connexion utilisateur

Swagger Petstore (Incorrect) :

GET /user/login?username=john&password=secret

Multiples problèmes :

• login est un verbe
• Utilisation de GET pour l'authentification (désastre de sécurité)
• Mots de passe dans les paramètres de requête URL

PetstoreAPI moderne (Correct) :

POST /auth/login
Content-Type: application/json

{
  "username": "john",
  "password": "secret123"
}

Avantages :

• Axé sur les ressources (/auth)
• Méthode HTTP correcte (POST)
• Identifiants dans le corps de la requête, pas dans l'URL
• Retourne un jeton JWT pour les requêtes ultérieures

Comment la PetstoreAPI moderne corrige cela

La PetstoreAPI moderne utilise des URL axées sur les ressources de manière cohérente.

Gestion des animaux

GET /pets                    ← Lister tous les animaux
GET /pets?status=AVAILABLE   ← Filtrer par statut
GET /pets?species=dog        ← Filtrer par espèce
GET /pets/{id}               ← Obtenir un animal spécifique
POST /pets                   ← Créer un nouvel animal
PUT /pets/{id}               ← Mettre à jour un animal
PATCH /pets/{id}             ← Mise à jour partielle
DELETE /pets/{id}            ← Supprimer un animal

Pas de verbes. Juste des ressources et des méthodes HTTP.

Gestion des commandes

GET /orders                  ← Lister les commandes
GET /orders/{id}             ← Obtenir une commande
POST /orders                 ← Créer une commande
PUT /orders/{id}             ← Mettre à jour une commande
DELETE /orders/{id}          ← Annuler une commande
GET /orders/{id}/items       ← Obtenir les articles d'une commande

Opérations complexes

Pour les opérations qui ne correspondent pas clairement au modèle CRUD, la PetstoreAPI moderne utilise des sous-ressources :

POST /orders/{id}/payment    ← Traiter le paiement d'une commande
POST /orders/{id}/shipment   ← Créer un envoi pour une commande
POST /pets/{id}/adoption     ← Lancer le processus d'adoption

Celles-ci restent axées sur les ressources. /orders/{id}/payment représente la ressource de paiement pour une commande.

Quand les verbes semblent nécessaires

Certaines opérations ne rentrent pas dans le modèle CRUD. Voici comment les gérer sans verbes dans les URL.

Opérations de recherche

Incorrect :

GET /searchPets?query=labrador

Option correcte 1 (Paramètres de requête) :

GET /pets?search=labrador

Option correcte 2 (Ressource de recherche) :

GET /pets/search?q=labrador

Option correcte 3 (Méthode QUERY) :

QUERY /pets
Content-Type: application/json

{
  "query": "labrador",
  "filters": {
    "status": "AVAILABLE"
  }
}

La PetstoreAPI moderne prend en charge les trois modèles selon la complexité.

Calculs

Incorrect :

GET /calculateShipping?weight=10&destination=NY

Correct :

GET /shipping-estimates?weight=10&destination=NY

La ressource est "estimations d'expédition", pas l'action de calcul.

Opérations par lots

Incorrect :

POST /batchDeletePets

Correct :

DELETE /pets?ids=1,2,3

Ou utiliser une ressource de lot :

POST /pets/batch-operations
Content-Type: application/json

{
  "operation": "delete",
  "ids": [1, 2, 3]
}

Actions qui modifient l'état

Incorrect :

POST /activateUser
POST /deactivateUser

Correct :

PATCH /users/{id}
Content-Type: application/json

{
  "status": "ACTIVE"
}

Les changements d'état sont des mises à jour de la ressource.

Tester la conception des URL avec Apidog

Apidog vous aide à valider la conception des API REST et à détecter l'utilisation de verbes dans les URL.

Importer la PetstoreAPI moderne

1. Importez la spécification OpenAPI de la PetstoreAPI moderne
2. Apidog génère automatiquement des cas de test
3. Examinez la structure et la nomenclature des endpoints

Vérifier les verbes dans les URL

Créez une règle de validation personnalisée dans Apidog :

// Check if URL contains common action verbs
const verbs = ['get', 'create', 'update', 'delete', 'find', 'search',
               'calculate', 'process', 'send', 'fetch'];
const url = request.url.toLowerCase();

for (const verb of verbs) {
  if (url.includes(`/${verb}`)) {
    throw new Error(`URL contains verb: ${verb}. Use resource-oriented URLs instead.`);
  }
}

Tester la cohérence des endpoints

Apidog peut vérifier que les endpoints liés suivent des modèles cohérents :

✓ GET /pets
✓ POST /pets
✓ GET /pets/{id}
✓ PUT /pets/{id}
✓ DELETE /pets/{id}

Tous utilisent la même ressource de base (/pets).

Comparer avec la PetstoreAPI moderne

Utilisez la PetstoreAPI moderne comme référence :

1. Importez votre API et la PetstoreAPI moderne dans Apidog
2. Comparez les structures des endpoints côte à côte
3. Identifiez les incohérences et l'utilisation des verbes
4. Refactorisez votre API pour qu'elle corresponde aux principes REST

Stratégies de migration

Si vous avez une API existante avec des verbes dans les URL, voici comment migrer.

Stratégie 1 : Versioning

Créez une nouvelle version d'API avec des URL correctes :

# Ancienne API (v1)
GET /api/v1/findPetsByStatus?status=available

# Nouvelle API (v2)
GET /api/v2/pets?status=available

Maintenez v1 pour la compatibilité descendante, encouragez la migration vers v2.

Stratégie 2 : Alias

Prenez en charge temporairement les anciennes et les nouvelles URL :

# Ancienne URL (dépréciée)
GET /pet/findByStatus?status=available

# Nouvelle URL (préférée)
GET /pets?status=available

Retournez des avertissements de dépréciation dans les réponses :

{
  "data": [...],
  "warnings": [
    {
      "code": "DEPRECATED_ENDPOINT",
      "message": "Ce point de terminaison est déprécié. Utilisez GET /pets?status=available à la place.",
      "sunset": "2027-01-01"
    }
  ]
}

Stratégie 3 : Redirections

Utilisez des redirections HTTP 301 pour les migrations simples :

GET /pet/findByStatus?status=available
→ 301 Moved Permanently
Location: /pets?status=available

Cela fonctionne pour les requêtes GET mais pas pour POST, PUT ou DELETE.

Conclusion

Les URL d'API REST doivent contenir des noms (ressources), et non des verbes (actions). Les méthodes HTTP fournissent les verbes. Ce principe crée des API cohérentes, évolutives et maintenables.

L'ancienne Swagger Petstore a violé ce principe avec des endpoints comme /pet/findByStatus. La PetstoreAPI moderne corrige cela en utilisant des URL axées sur les ressources de manière cohérente : /pets?status=AVAILABLE.

Points clés à retenir :

• Utilisez des noms dans les URL : /pets, /orders, /users
• Laissez les méthodes HTTP être les verbes : GET, POST, PUT, DELETE
• Utilisez des paramètres de requête pour le filtrage : /pets?status=available
• Pour les opérations complexes, utilisez des sous-ressources : /orders/{id}/payment
• Testez la conception de votre API avec Apidog pour détecter l'utilisation de verbes tôt

Consultez la documentation de la PetstoreAPI moderne pour des exemples complets de conception d'URL axées sur les ressources.

FAQ

Puis-je utiliser des verbes dans les URL REST ?

Rarement. Si une opération ne correspond vraiment pas au modèle de ressource (comme /search ou /login), un verbe pourrait être acceptable. Mais 95 % du temps, vous pouvez le modéliser comme une ressource.

Qu'en est-il de /login et /logout ?

Ce sont des exceptions courantes. De nombreuses API utilisent /auth/login et /auth/logout. Alternativement, modelez-les comme des ressources : POST /sessions (connexion) et DELETE /sessions/{id} (déconnexion).

Comment gérer les requêtes complexes ?

Utilisez des paramètres de requête pour un filtrage simple : /pets?status=available&species=dog. Pour les requêtes complexes, utilisez la méthode HTTP QUERY ou une ressource de recherche : POST /pets/search.

Que faire si mon opération ne correspond pas au CRUD ?

Modélisez-la comme une sous-ressource. Au lieu de POST /processPayment, utilisez POST /orders/{id}/payment. Le paiement est une ressource liée à la commande.

Comment vérifier si mes URL sont axées sur les ressources ?

Utilisez Apidog pour importer votre spécification OpenAPI et vérifier les verbes dans les URL. Comparez la structure de votre API avec la PetstoreAPI moderne comme référence.

Dois-je utiliser /pets/search ou /pets?search=query ?

Les deux sont acceptables. /pets?search=query est plus simple pour une recherche basique. /pets/search ou QUERY /pets fonctionne mieux pour une recherche complexe avec plusieurs paramètres.

Comment migrer à partir d'URL basées sur des verbes ?

Utilisez le versioning de l'API (/v2/pets au lieu de /v1/findPets), ajoutez des avertissements de dépréciation et donnez aux clients le temps de migrer. Consultez la section Stratégies de migration pour plus de détails.

La PetstoreAPI moderne utilise-t-elle des verbes dans les URL ?

La PetstoreAPI moderne évite les verbes dans les URL. Les opérations comme la recherche, le filtrage et l'authentification sont modélisées comme des ressources ou utilisent des paramètres de requête. Consultez la documentation de l'API REST pour des exemples.