Blog

Pourquoi l'exemple Swagger Petstore est-il une mauvaise conception d'API REST ?

Ashley Innocent

Ashley Innocent

13 March 2026

Pourquoi l'exemple Swagger Petstore est-il une mauvaise conception d'API REST ?

enterprise.banner.title

enterprise.banner.feature1

enterprise.banner.feature2

enterprise.banner.feature3

enterprise.banner.ctaB

En bref (TL;DR)

Le Swagger Petstore viole des principes REST fondamentaux : il utilise des noms de ressources au singulier de manière incohérente, inclut des verbes d'action dans les URL, renvoie des codes d'état HTTP incorrects, expose des mots de passe dans les requêtes GET et renvoie des tableaux bruts sans métadonnées. Le Modern PetstoreAPI corrige tous ces problèmes avec une conception RESTful appropriée, une gestion des erreurs RFC 9457 et des modèles prêts pour la production.

Introduction

Pendant plus d'une décennie, le Swagger Petstore a été l'exemple par défaut pour apprendre OpenAPI. Des millions de développeurs l'ont étudié, copié ses modèles et construit des API de production basées sur sa conception. Il y a un problème : il vous apprend à construire de mauvaises API.

Le Swagger Petstore viole les principes REST de base, inclut des vulnérabilités de sécurité et démontre des anti-modèles qui nuisent aux systèmes de production. C'est comme apprendre à conduire avec une voiture dont les pédales de frein et d'accélérateur sont inversées — vous apprendrez, mais vous apprendrez mal.

Les dégâts sont réels. Les développeurs qui ont appris du Swagger Petstore intègrent ces anti-modèles dans le code de production. Les API sont construites avec des noms incohérents, de mauvaises méthodes HTTP et des failles de sécurité. Les revues de code passent à côté de ces problèmes car « c'est comme ça que Petstore le fait. »

💡
Si vous construisez ou testez des API REST, Apidog vous aide à valider la conception des API par rapport aux principes REST, à tester le comportement des points de terminaison et à détecter les défauts de conception avant qu'ils n'atteignent la production. Vous pouvez importer des spécifications OpenAPI, exécuter des tests automatisés et vous assurer que votre API respecte les conventions REST appropriées.
bouton

Dans ce guide, vous apprendrez précisément ce qui ne va pas avec le Swagger Petstore, pourquoi ces problèmes sont importants et comment Modern PetstoreAPI les corrige avec des modèles prêts pour la production. Vous verrez des comparaisons côte à côte, comprendrez l'impact de chaque violation et découvrirez comment tester correctement vos API avec Apidog.

Le problème de l'héritage du Swagger Petstore

Le Swagger Petstore a été créé en 2011 comme un exemple simple pour la spécification Swagger (maintenant OpenAPI). Il a rempli son objectif : démontrer comment écrire une spécification OpenAPI. Mais il n'a jamais été conçu pour être une référence en matière de conception d'API REST.

Pourquoi il est devenu la norme de facto

Lorsque les développeurs apprennent OpenAPI, ils commencent par l'exemple officiel. Le Swagger Petstore est cet exemple. Il est présent dans la documentation, les tutoriels et les générateurs de code. Si vous avez utilisé Swagger UI ou Swagger Codegen, vous l'avez vu.

Le problème : les développeurs supposent que « l'exemple officiel = meilleure pratique ». Ils copient les modèles sans les remettre en question. Les cours de conception d'API l'utilisent comme outil pédagogique. Les entreprises construisent des API internes en suivant sa structure.

Le coût des mauvais exemples

Les mauvais exemples s'accumulent avec le temps :

  1. Les développeurs juniors apprennent des anti-modèles - Ils ne savent pas que ce sont des erreurs
  2. Les générateurs de code perpétuent les problèmes - Les SDK générés héritent des défauts
  3. Les outils de documentation affichent de mauvais exemples - Swagger UI affiche le Petstore par défaut
  4. Les entreprises construisent des API de production de cette manière - « Si c'est suffisant pour Swagger… »

Le Swagger Petstore a probablement influencé plus de conceptions d'API que tout autre exemple dans l'histoire. C'est pourquoi ses défauts sont importants.

Violations REST critiques dans le Swagger Petstore

Examinons les violations REST spécifiques dans le Swagger Petstore et pourquoi elles sont incorrectes.

1. Nommage de ressources incohérent (pluriel vs singulier)

La violation :

GET /pet/{petId}           ← Singulier
GET /store/inventory       ← Pluriel
POST /pet                  ← Singulier
GET /user/{username}       ← Singulier

Pourquoi c'est incorrect :

Les ressources REST représentent des collections. Une collection est au pluriel. Lorsque vous accédez à /pets, vous accédez à la collection d'animaux. Lorsque vous accédez à /pets/123, vous accédez à l'élément 123 de la collection d'animaux.

Mélanger le singulier et le pluriel brise ce modèle mental. Est-ce que /pet/123 accède à la collection d'animaux ou à une seule ressource d'animal ? L'incohérence crée de la confusion.

La correction de Modern PetstoreAPI :

GET /pets/{petId}          ← Toujours pluriel
GET /stores/inventory      ← Cohérent
POST /pets                 ← Pluriel pour la collection
GET /users/{username}      ← Pluriel partout

Modern PetstoreAPI utilise des noms de ressources au pluriel de manière cohérente sur tous les points de terminaison. Consultez la documentation de l'API REST pour la structure complète des points de terminaison.

2. Verbes d'action dans les URL

La violation :

GET /pet/findByStatus?status=available
GET /pet/findByTags?tags=tag1,tag2
GET /user/login?username=john&password=secret
GET /user/logout

Pourquoi c'est incorrect :

Les URL REST doivent représenter des ressources (noms), pas des actions (verbes). La méthode HTTP est le verbe. GET /pets signifie « obtenir la ressource des animaux ». L'ajout de findByStatus est redondant — c'est à cela que servent les paramètres de requête.

Les verbes d'action dans les URL indiquent que vous pensez en termes d'appel de procédure distante (RPC), et non en termes REST. Vous exposez des détails d'implémentation au lieu de ressources.

La correction de Modern PetstoreAPI :

GET /pets?status=AVAILABLE              ← Ressource + filtre
GET /pets?tags=tag1,tag2                ← Paramètres de requête pour le filtrage
POST /auth/login                        ← Ressource d'authentification séparée
POST /auth/logout                       ← Points de terminaison d'authentification RESTful

Le Modern PetstoreAPI utilise des paramètres de requête pour le filtrage et des ressources d'authentification distinctes. Consultez le guide d'authentification pour les modèles d'authentification appropriés.

3. Codes d'état HTTP incorrects

La violation :

POST /pet
Réponse : 200 OK          ← Devrait être 201 Created

DELETE /pet/{petId}
Réponse : 200 OK          ← Devrait être 204 No Content
{
  "message": "Animal supprimé"
}

Pourquoi c'est incorrect :

Les codes d'état HTTP ont des significations spécifiques :

Utiliser 200 pour tout brise la sémantique HTTP. Les clients ne peuvent pas distinguer entre « ressource récupérée » et « ressource créée ». Renvoyer un corps avec DELETE gaspille de la bande passante — le client n'a pas besoin de texte de confirmation.

La correction de Modern PetstoreAPI :

POST /pets
Réponse : 201 Created
Location: /pets/019b4132-70aa-764f-b315-e2803d882a24
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "status": "AVAILABLE"
}

DELETE /pets/{petId}
Réponse : 204 No Content
(aucun corps)

Modern PetstoreAPI utilise des codes d'état HTTP corrects et inclut des en-têtes Location pour les ressources créées. Consultez le guide des codes d'état HTTP pour le mappage complet.

4. Tableaux bruts sans métadonnées

La violation :

GET /pet/findByStatus?status=available
Réponse : 200 OK
[
  {"id": 1, "name": "Fluffy"},
  {"id": 2, "name": "Buddy"}
]

Pourquoi c'est incorrect :

Renvoyer des tableaux bruts crée des problèmes :

La correction de Modern PetstoreAPI :

GET /pets?status=AVAILABLE
Réponse : 200 OK
{
  "data": [
    {"id": "019b4132-70aa-764f-b315-e2803d882a24", "name": "Fluffy"},
    {"id": "019b4127-54d5-76d9-b626-0d4c7bfce5b6", "name": "Buddy"}
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalItems": 45,
    "totalPages": 3
  },
  "links": {
    "self": "/pets?status=AVAILABLE&page=1",
    "next": "/pets?status=AVAILABLE&page=2",
    "last": "/pets?status=AVAILABLE&page=3"
  }
}

Modern PetstoreAPI encapsule toutes les collections dans des objets avec des métadonnées et des liens HATEOAS. Consultez le guide de pagination pour les détails d'implémentation.

5. Normes d'erreur manquantes

La violation :

Réponse : 400 Bad Request
{
  "code": 400,
  "message": "Entrée invalide"
}

Pourquoi c'est incorrect :

Ce format d'erreur est non standard et fournit des informations minimales :

La correction de Modern PetstoreAPI :

Réponse : 400 Bad Request
Content-Type: application/problem+json
{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Erreur de validation",
  "status": 400,
  "detail": "La validation de la requête a échoué",
  "instance": "/pets",
  "errors": [
    {
      "field": "name",
      "message": "Le nom est requis",
      "code": "REQUIRED_FIELD"
    },
    {
      "field": "status",
      "message": "Le statut doit être l'un des suivants : AVAILABLE, PENDING, SOLD",
      "code": "INVALID_ENUM"
    }
  ]
}

Modern PetstoreAPI utilise la RFC 9457 Problem Details pour toutes les erreurs. Consultez le guide de gestion des erreurs pour le format d'erreur complet.

Désastres de sécurité dans l'ancienne conception

Au-delà des violations REST, le Swagger Petstore présente de graves problèmes de sécurité.

Requête GET avec mots de passe

La violation :

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

Pourquoi c'est un désastre :

Les mots de passe dans les requêtes GET apparaissent dans :

Il s'agit d'une vulnérabilité de sécurité critique. Les mots de passe ne devraient jamais se trouver dans les URL.

La correction de Modern PetstoreAPI :

POST /auth/login
Content-Type: application/json
{
  "username": "john",
  "password": "secret123"
}

Réponse : 200 OK
{
  "accessToken": "eyJhbGc...",
  "refreshToken": "eyJhbGc...",
  "expiresIn": 3600
}

Modern PetstoreAPI utilise POST pour l'authentification avec des corps JSON. Les mots de passe n'apparaissent jamais dans les URL. Consultez le guide d'authentification pour les modèles OAuth 2.0 et JWT.

Clés API dans les paramètres de requête

La violation :

GET /pet/123?api_key=abc123secret

Pourquoi c'est incorrect :

Les clés API dans les paramètres de requête présentent les mêmes problèmes que les mots de passe dans les URL :

La correction de Modern PetstoreAPI :

GET /pets/019b4132-70aa-764f-b315-e2803d882a24
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Modern PetstoreAPI utilise les en-têtes Authorization standard pour les clés API et les jetons. Consultez le guide de sécurité pour les modèles d'authentification.

Comment Modern PetstoreAPI corrige ces problèmes

Modern PetstoreAPI a été construit de zéro pour démontrer une conception d'API REST appropriée. Voici ce qui le rend différent :

Conception REST prête pour la production

Normes modernes

Support multi-protocole

Contrairement au Swagger Petstore (REST uniquement), Modern PetstoreAPI prend en charge :

Consultez le guide des protocoles pour les détails d'implémentation.

Logique métier réelle

Modern PetstoreAPI inclut des fonctionnalités réalistes :

Consultez la documentation API pour l'ensemble complet des fonctionnalités.

Tester la conception d'API REST avec Apidog

Apidog vous aide à valider la conception d'API REST et à détecter les violations avant qu'elles n'atteignent la production.

Importer et valider les spécifications OpenAPI

# Importer la spécification Modern PetstoreAPI
1. Ouvrez Apidog
2. Cliquez sur "Importer" → "OpenAPI"
3. Entrez : https://petstoreapi.com/openapi.json
4. Apidog valide la spécification et crée des cas de test

Apidog détecte automatiquement :

Tester les principes REST

Créez des cas de test qui vérifient la conformité REST :

Test : Les noms de ressources sont au pluriel

// Script de test Apidog
pm.test("Le point de terminaison utilise un nom de ressource au pluriel", function() {
  const url = pm.request.url.toString();
  pm.expect(url).to.match(/\/pets\/|\/orders\/|\/users\//);
  pm.expect(url).to.not.match(/\/pet\/|\/order\/|\/user\//);
});

Test : Codes d'état corrects

pm.test("POST renvoie 201 Created", function() {
  if (pm.request.method === "POST") {
    pm.response.to.have.status(201);
    pm.response.to.have.header("Location");
  }
});

pm.test("DELETE renvoie 204 No Content", function() {
  if (pm.request.method === "DELETE") {
    pm.response.to.have.status(204);
    pm.expect(pm.response.text()).to.be.empty;
  }
});

Test : Les collections ont des métadonnées

pm.test("La réponse de la collection inclut la pagination", function() {
  const response = pm.response.json();
  pm.expect(response).to.have.property("data");
  pm.expect(response).to.have.property("pagination");
  pm.expect(response.pagination).to.have.property("page");
  pm.expect(response.pagination).to.have.property("totalItems");
});

Comparer l'ancien et le nouveau Petstore

Importez les deux spécifications dans Apidog et exécutez des comparaisons côte à côte :

  1. Importez le Swagger Petstore : https://petstore.swagger.io/v2/swagger.json
  2. Importez le Modern PetstoreAPI : https://petstoreapi.com/openapi.json
  3. Exécutez des tests automatisés sur les deux
  4. Comparez les résultats pour voir les différences

Apidog mettra en évidence les violations de conception dans le Swagger Petstore et montrera comment Modern PetstoreAPI les corrige.

Guide de migration : de l'ancien Petstore à la conception moderne

Si vous avez construit une API basée sur le Swagger Petstore, voici comment migrer vers une conception REST appropriée :

Étape 1 : Corriger les noms de ressources

Avant :

GET /pet/{petId}
POST /pet
DELETE /pet/{petId}

Après :

GET /pets/{petId}
POST /pets
DELETE /pets/{petId}

Stratégie de migration :

Étape 2 : Supprimer les verbes d'action

Avant :

GET /pet/findByStatus?status=available
GET /pet/findByTags?tags=tag1,tag2

Après :

GET /pets?status=AVAILABLE
GET /pets?tags=tag1,tag2

Stratégie de migration :

Étape 3 : Corriger les codes d'état HTTP

Avant :

POST /pet → 200 OK
DELETE /pet/{petId} → 200 OK avec corps

Après :

POST /pets → 201 Created avec en-tête Location
DELETE /pets/{petId} → 204 No Content (aucun corps)

Stratégie de migration :

Étape 4 : Encapsuler les collections

Avant :

[
  {"id": 1, "name": "Fluffy"},
  {"id": 2, "name": "Buddy"}
]

Après :

{
  "data": [...],
  "pagination": {...},
  "links": {...}
}

Stratégie de migration :

Étape 5 : Implémenter les erreurs RFC 9457

Avant :

{
  "code": 400,
  "message": "Entrée invalide"
}

Après :

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Erreur de validation",
  "status": 400,
  "detail": "La validation de la requête a échoué",
  "errors": [...]
}

Stratégie de migration :

Impact réel d'une mauvaise conception d'API

Une mauvaise conception d'API a des coûts réels :

Confusion des développeurs

Lorsque les API violent les principes REST, les développeurs perdent du temps à :

Coût : Heures de temps de développeur par intégration

Bugs clients

Les API incohérentes entraînent des bugs côté client :

Coût : Incidents de production et impact sur les clients

Vulnérabilités de sécurité

Les défauts de conception créent des risques de sécurité :

Coût : Violations de données et non-conformité

Dette technique

Les mauvais exemples s'accumulent avec le temps :

Coût : Charge de maintenance à long terme

Conclusion

Le Swagger Petstore a rempli son rôle d'exemple OpenAPI simple, mais il est temps de passer à autre chose. Ses violations REST, ses problèmes de sécurité et ses anti-modèles ont influencé trop d'API de production.

Modern PetstoreAPI fournit l'implémentation de référence dont l'industrie a besoin : une conception REST appropriée, des normes modernes, un support multi-protocole et des modèles prêts pour la production. Utilisez-le comme ressource d'apprentissage et référence pour la conception d'API.

Testez vos API avec Apidog pour détecter les violations de conception dès le début. Importez vos spécifications OpenAPI, exécutez des tests automatisés et assurez-vous que vos API respectent les principes REST avant qu'elles n'atteignent la production.

Étapes suivantes :

  1. Explorez la documentation Modern PetstoreAPI
  2. Comparez la conception de votre API aux modèles Modern PetstoreAPI
  3. Importez votre spécification OpenAPI dans Apidog pour validation
  4. Corrigez les violations REST à l'aide du guide de migration ci-dessus
  5. Adoptez la RFC 9457 pour la gestion des erreurs

L'ère des mauvais exemples d'API est révolue. Construisez des API de la bonne manière avec Modern PetstoreAPI.

FAQ

Pourquoi Swagger a-t-il créé un mauvais exemple ?

Le Swagger Petstore a été créé en 2011 comme une simple démonstration de la spécification Swagger. Il n'était pas destiné à être une référence en matière de conception d'API REST. Le problème est qu'il est devenu l'exemple de facto standard, et ses défauts ont été copiés par des millions de développeurs.

Devrais-je arrêter d'utiliser le Swagger Petstore ?

Oui, pour apprendre la conception d'API REST. Utilisez Modern PetstoreAPI à la place. Il démontre les principes REST appropriés, les normes modernes et les modèles prêts pour la production. L'ancien Petstore enseigne des anti-modèles qui nuisent aux systèmes de production.

Modern PetstoreAPI est-il prêt pour la production ?

Oui. Modern PetstoreAPI inclut une logique métier réaliste, une gestion des erreurs appropriée, l'authentification, la limitation de débit et des fonctionnalités de sécurité. Vous pouvez le déployer avec des modifications minimales ou l'utiliser comme référence pour la conception de votre propre API.

Comment puis-je tester si mon API respecte les principes REST ?

Importez votre spécification OpenAPI dans Apidog et exécutez des tests automatisés. Apidog valide le nommage des ressources, les codes d'état HTTP, les structures de réponse et les modèles de sécurité. Vous pouvez également comparer votre API côte à côte avec Modern PetstoreAPI.

Quelle est la plus grande erreur dans le Swagger Petstore ?

Utiliser GET /user/login avec des mots de passe dans les paramètres de requête. Cela expose les mots de passe dans l'historique du navigateur, les journaux du serveur et les en-têtes referrer — une vulnérabilité de sécurité critique. Utilisez toujours POST avec des corps JSON pour l'authentification.

Puis-je migrer progressivement des modèles Swagger Petstore ?

Oui. Prenez en charge les anciens et les nouveaux points de terminaison pendant une période de transition. Ajoutez des avertissements de dépréciation aux anciens points de terminaison, mettez à jour la documentation et surveillez l'utilisation. Supprimez les anciens points de terminaison après que les clients ont migré (généralement 6 à 12 mois).

Modern PetstoreAPI prend-il en charge GraphQL et gRPC ?

Oui. Contrairement au Swagger Petstore (REST uniquement), Modern PetstoreAPI prend en charge plusieurs protocoles : REST, GraphQL, gRPC, WebSocket, SSE, MQTT, Webhooks et MCP. Consultez le guide des protocoles pour plus de détails.

Comment puis-je convaincre mon équipe de corriger la conception de notre API ?

Montrez-leur les coûts réels : confusion des développeurs, bugs clients, vulnérabilités de sécurité et dette technique. Utilisez Apidog pour démontrer les violations dans votre API actuelle. Comparez votre conception à Modern PetstoreAPI et montrez les améliorations.

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API

S'inscrire gratuitementTélécharger
Pourquoi l'exemple Swagger Petstore est-il une mauvaise conception d'API REST ?