Blog

¿Por Qué El Ejemplo Swagger Petstore Es Un Mal Diseño De API REST?

Ashley Innocent

Ashley Innocent

13 March 2026

¿Por Qué El Ejemplo Swagger Petstore Es Un Mal Diseño De API REST?

Apidog para empresas

Despliegue local

SSO & RBAC

Conforme con SOC 2

Explorar Apidog Enterprise

En resumen

El Swagger Petstore viola principios REST fundamentales: utiliza nombres de recursos singulares de forma inconsistente, incluye verbos de acción en las URLs, devuelve códigos de estado HTTP incorrectos, expone contraseñas en solicitudes GET y devuelve arrays desnudos sin metadatos. Modern PetstoreAPI soluciona todos estos problemas con un diseño RESTful adecuado, manejo de errores RFC 9457 y patrones listos para producción.

Introducción

Durante más de una década, Swagger Petstore ha sido el ejemplo predeterminado para aprender OpenAPI. Millones de desarrolladores lo han estudiado, copiado sus patrones y construido APIs de producción basándose en su diseño. Hay un problema: te enseña a construir APIs defectuosas.

Swagger Petstore viola los principios básicos de REST, incluye vulnerabilidades de seguridad y demuestra antipatrones que perjudican los sistemas de producción. Es como aprender a conducir con un coche que tiene los pedales de freno y acelerador intercambiados: aprenderás, pero aprenderás mal.

El daño es real. Los desarrolladores que aprendieron de Swagger Petstore llevan estos antipatrones al código de producción. Las APIs se construyen con nombres inconsistentes, métodos HTTP incorrectos y agujeros de seguridad. Las revisiones de código pasan por alto estos problemas porque “así es como lo hace Petstore”.

💡
Si estás construyendo o probando APIs REST, Apidog te ayuda a validar el diseño de la API según los principios REST, probar el comportamiento de los endpoints y detectar fallos de diseño antes de que lleguen a producción. Puedes importar especificaciones OpenAPI, ejecutar pruebas automatizadas y asegurar que tu API sigue las convenciones REST adecuadas.
botón

En esta guía, aprenderás exactamente qué está mal con Swagger Petstore, por qué estos problemas importan y cómo Modern PetstoreAPI los soluciona con patrones listos para producción. Verás comparaciones lado a lado, comprenderás el impacto de cada violación y descubrirás cómo probar tus APIs correctamente con Apidog.

El Problema del Legado de Swagger Petstore

Swagger Petstore fue creado en 2011 como un ejemplo simple para la especificación Swagger (ahora OpenAPI). Cumplió su propósito: demostrar cómo escribir una especificación OpenAPI. Pero nunca tuvo la intención de ser una referencia para el diseño de APIs REST.

Por qué se Convirtió en el Estándar De Facto

Cuando los desarrolladores aprenden OpenAPI, comienzan con el ejemplo oficial. Swagger Petstore es ese ejemplo. Se encuentra en la documentación, tutoriales y generadores de código. Si has usado Swagger UI o Swagger Codegen, lo habrás visto.

El problema: los desarrolladores asumen que “ejemplo oficial = mejor práctica”. Copian los patrones sin cuestionarlos. Los cursos de diseño de APIs lo usan como herramienta de enseñanza. Las empresas construyen APIs internas siguiendo su estructura.

El Costo de los Malos Ejemplos

Los malos ejemplos se acumulan con el tiempo:

  1. Los desarrolladores junior aprenden antipatrones - No saben que son errores
  2. Los generadores de código perpetúan los problemas - Los SDKs generados heredan los defectos
  3. Las herramientas de documentación muestran malos ejemplos - Swagger UI muestra Petstore por defecto
  4. Las empresas construyen APIs de producción de esta manera - “Si es lo suficientemente bueno para Swagger…”

Swagger Petstore probablemente ha influido en más diseños de APIs que cualquier otro ejemplo en la historia. Por eso sus defectos importan.

Violaciones Críticas de REST en Swagger Petstore

Examinemos las violaciones específicas de REST en Swagger Petstore y por qué están mal.

1. Nomenclatura Inconsistente de Recursos (Plural vs Singular)

La Violación:

GET /pet/{petId}           ← Singular
GET /store/inventory       ← Plural
POST /pet                  ← Singular
GET /user/{username}       ← Singular

Por qué Está Mal:

Los recursos REST representan colecciones. Una colección es plural. Cuando accedes a /pets, estás accediendo a la colección de mascotas. Cuando accedes a /pets/123, estás accediendo al elemento 123 de la colección de mascotas.

Mezclar singular y plural rompe este modelo mental. ¿Está /pet/123 accediendo a la colección de mascotas o a un solo recurso de mascota? La inconsistencia crea confusión.

Solución de Modern PetstoreAPI:

GET /pets/{petId}          ← Siempre plural
GET /stores/inventory      ← Consistente
POST /pets                 ← Plural para colección
GET /users/{username}      ← Plural en todas partes

Modern PetstoreAPI utiliza nombres de recursos plurales de forma consistente en todos los endpoints. Consulta la documentación de la API REST para la estructura completa de los endpoints.

2. Verbos de Acción en URLs

La Violación:

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

Por qué Está Mal:

Las URLs REST deben representar recursos (sustantivos), no acciones (verbos). El método HTTP es el verbo. GET /pets significa “obtener el recurso de mascotas”. Añadir findByStatus es redundante; para eso están los parámetros de consulta.

Los verbos de acción en las URLs indican que estás pensando en términos de RPC (Llamada a Procedimiento Remoto), no en términos de REST. Estás exponiendo detalles de implementación en lugar de recursos.

Solución de Modern PetstoreAPI:

GET /pets?status=AVAILABLE              ← Recurso + filtro
GET /pets?tags=tag1,tag2                ← Parámetros de consulta para filtrar
POST /auth/login                        ← Recurso de autenticación separado
POST /auth/logout                       ← Endpoints de autenticación RESTful

La Modern PetstoreAPI utiliza parámetros de consulta para filtrar y recursos de autenticación separados. Consulta la guía de autenticación para conocer los patrones de autenticación adecuados.

3. Códigos de Estado HTTP Incorrectos

La Violación:

POST /pet
Response: 200 OK          ← Debería ser 201 Created

DELETE /pet/{petId}
Response: 200 OK          ← Debería ser 204 No Content
{
  "message": "Pet deleted"
}

Por qué Está Mal:

Los códigos de estado HTTP tienen significados específicos:

Usar 200 para todo rompe la semántica HTTP. Los clientes no pueden distinguir entre “recurso recuperado” y “recurso creado”. Devolver un cuerpo con DELETE desperdicia ancho de banda; el cliente no necesita texto de confirmación.

Solución de Modern PetstoreAPI:

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

DELETE /pets/{petId}
Response: 204 No Content
(sin cuerpo)

Modern PetstoreAPI utiliza códigos de estado HTTP correctos e incluye cabeceras Location para los recursos creados. Consulta la guía de códigos de estado HTTP para el mapeo completo.

4. Arrays Desnudos Sin Metadatos

La Violación:

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

Por qué Está Mal:

Devolver arrays desnudos crea problemas:

Solución de Modern PetstoreAPI:

GET /pets?status=AVAILABLE
Response: 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 envuelve todas las colecciones en objetos con metadatos y enlaces HATEOAS. Consulta la guía de paginación para detalles de implementación.

5. Ausencia de Estándares de Error

La Violación:

Response: 400 Bad Request
{
  "code": 400,
  "message": "Invalid input"
}

Por qué Está Mal:

Este formato de error no es estándar y proporciona información mínima:

Solución de Modern PetstoreAPI:

Response: 400 Bad Request
Content-Type: application/problem+json
{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/pets",
  "errors": [
    {
      "field": "name",
      "message": "Name is required",
      "code": "REQUIRED_FIELD"
    },
    {
      "field": "status",
      "message": "Status must be one of: AVAILABLE, PENDING, SOLD",
      "code": "INVALID_ENUM"
    }
  ]
}

Modern PetstoreAPI utiliza los Detalles del Problema de RFC 9457 para todos los errores. Consulta la guía de manejo de errores para el formato de error completo.

Desastres de Seguridad en el Diseño Antiguo

Más allá de las violaciones de REST, Swagger Petstore tiene graves problemas de seguridad.

Solicitudes GET con Contraseñas

La Violación:

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

Por qué es un Desastre:

Las contraseñas en las solicitudes GET aparecen en:

Esto es una vulnerabilidad de seguridad crítica. Las contraseñas nunca deben estar en las URLs.

Solución de Modern PetstoreAPI:

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

Response: 200 OK
{
  "accessToken": "eyJhbGc...",
  "refreshToken": "eyJhbGc...",
  "expiresIn": 3600
}

Modern PetstoreAPI usa POST para la autenticación con cuerpos JSON. Las contraseñas nunca aparecen en las URLs. Consulta la guía de autenticación para patrones de OAuth 2.0 y JWT.

Claves de API en Parámetros de Consulta

La Violación:

GET /pet/123?api_key=abc123secret

Por qué Está Mal:

Las claves de API en los parámetros de consulta tienen los mismos problemas que las contraseñas en las URLs:

Solución de Modern PetstoreAPI:

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

Modern PetstoreAPI usa cabeceras Authorization estándar para claves y tokens de API. Consulta la guía de seguridad para patrones de autenticación.

Cómo Modern PetstoreAPI Soluciona Estos Problemas

Modern PetstoreAPI fue construida desde cero para demostrar un diseño de API REST adecuado. Esto es lo que la hace diferente:

Diseño REST Listo para Producción

Estándares Modernos

Soporte Multi-Protocolo

A diferencia de Swagger Petstore (solo REST), Modern PetstoreAPI soporta:

Consulta la guía de protocolos para detalles de implementación.

Lógica de Negocio Real

Modern PetstoreAPI incluye características realistas:

Consulta la documentación de la API para el conjunto completo de características.

Probando el Diseño de APIs REST con Apidog

Apidog te ayuda a validar el diseño de APIs REST y a detectar violaciones antes de que lleguen a producción.

Importar y Validar Especificaciones OpenAPI

# Importar la especificación de Modern PetstoreAPI
1. Abrir Apidog
2. Clic en "Importar" → "OpenAPI"
3. Introducir: https://petstoreapi.com/openapi.json
4. Apidog valida la especificación y crea casos de prueba

Apidog detecta automáticamente:

Probar Principios REST

Crear casos de prueba que verifiquen la conformidad con REST:

Prueba: Los Nombres de Recursos Son Plurales

// Script de prueba de Apidog
pm.test("El endpoint usa nombres de recursos plurales", function() {
  const url = pm.request.url.toString();
  pm.expect(url).to.match(/\/pets\/|\/orders\/|\/users\//);
  pm.expect(url).to.not.match(/\/pet\/|\/order\/|\/user\//);
});

Prueba: Códigos de Estado Correctos

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

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

Prueba: Las Colecciones Tienen Metadatos

pm.test("La respuesta de la colección incluye paginación", 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");
});

Comparar Petstore Antiguo vs Moderno

Importa ambas especificaciones en Apidog y ejecuta comparaciones lado a lado:

  1. Importar Swagger Petstore: https://petstore.swagger.io/v2/swagger.json
  2. Importar Modern PetstoreAPI: https://petstoreapi.com/openapi.json
  3. Ejecutar pruebas automatizadas en ambos
  4. Comparar resultados para ver las diferencias

Apidog destacará las violaciones de diseño en Swagger Petstore y mostrará cómo Modern PetstoreAPI las soluciona.

Guía de Migración: De Petstore Antiguo a Diseño Moderno

Si construiste una API basándote en Swagger Petstore, aquí te explicamos cómo migrar a un diseño REST adecuado:

Paso 1: Corregir Nombres de Recursos

Antes:

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

Después:

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

Estrategia de Migración:

Paso 2: Eliminar Verbos de Acción

Antes:

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

Después:

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

Estrategia de Migración:

Paso 3: Corregir Códigos de Estado HTTP

Antes:

POST /pet → 200 OK
DELETE /pet/{petId} → 200 OK con cuerpo

Después:

POST /pets → 201 Created con cabecera Location
DELETE /pets/{petId} → 204 No Content (sin cuerpo)

Estrategia de Migración:

Paso 4: Envolver Colecciones

Antes:

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

Después:

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

Estrategia de Migración:

Paso 5: Implementar Errores RFC 9457

Antes:

{
  "code": 400,
  "message": "Invalid input"
}

Después:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [...]
}

Estrategia de Migración:

Impacto Real de un Mal Diseño de API

Un mal diseño de API tiene costos reales:

Confusión del Desarrollador

Cuando las APIs violan los principios REST, los desarrolladores pierden el tiempo:

Costo: Horas de tiempo de desarrollador por integración

Errores del Cliente

Las APIs inconsistentes llevan a errores del lado del cliente:

Costo: Incidentes de producción e impacto en el cliente

Vulnerabilidades de Seguridad

Los defectos de diseño crean riesgos de seguridad:

Costo: Filtraciones de datos y violaciones de cumplimiento

Deuda Técnica

Los malos ejemplos se acumulan con el tiempo:

Costo: Carga de mantenimiento a largo plazo

Conclusión

Swagger Petstore cumplió su propósito como un simple ejemplo de OpenAPI, pero es hora de avanzar. Sus violaciones de REST, problemas de seguridad y antipatrones han influido en demasiadas APIs de producción.

Modern PetstoreAPI proporciona la implementación de referencia que la industria necesita: diseño REST adecuado, estándares modernos, soporte multiprotocolo y patrones listos para producción. Úsala como tu recurso de aprendizaje y referencia para el diseño de APIs.

Prueba tus APIs con Apidog para detectar violaciones de diseño a tiempo. Importa tus especificaciones OpenAPI, ejecuta pruebas automatizadas y asegúrate de que tus APIs sigan los principios REST antes de que lleguen a producción.

Próximos Pasos:

  1. Explora la documentación de Modern PetstoreAPI
  2. Compara el diseño de tu API con los patrones de Modern PetstoreAPI
  3. Importa tu especificación OpenAPI en Apidog para su validación
  4. Soluciona las violaciones REST usando la guía de migración anterior
  5. Adopta RFC 9457 para el manejo de errores

La era de los malos ejemplos de API ha terminado. Construye APIs de la manera correcta con Modern PetstoreAPI.

Preguntas Frecuentes

¿Por qué Swagger creó un mal ejemplo?

Swagger Petstore fue creado en 2011 como una simple demostración de la especificación Swagger. No estaba destinado a ser una referencia de diseño de API REST. El problema es que se convirtió en el ejemplo estándar de facto, y sus defectos fueron copiados por millones de desarrolladores.

¿Debería dejar de usar Swagger Petstore?

Sí, para aprender diseño de API REST. Usa Modern PetstoreAPI en su lugar. Demuestra principios REST adecuados, estándares modernos y patrones listos para producción. El antiguo Petstore enseña antipatrones que perjudican los sistemas de producción.

¿Está Modern PetstoreAPI lista para producción?

Sí. Modern PetstoreAPI incluye lógica de negocio realista, manejo de errores adecuado, autenticación, limitación de tasa y características de seguridad. Puedes desplegarla con mínimas modificaciones o usarla como referencia para tu propio diseño de API.

¿Cómo pruebo si mi API sigue los principios REST?

Importa tu especificación OpenAPI en Apidog y ejecuta pruebas automatizadas. Apidog valida la nomenclatura de recursos, los códigos de estado HTTP, las estructuras de respuesta y los patrones de seguridad. También puedes comparar tu API lado a lado con Modern PetstoreAPI.

¿Cuál es el mayor error en Swagger Petstore?

Usar GET /user/login con contraseñas en los parámetros de consulta. Esto expone las contraseñas en el historial del navegador, los registros del servidor y las cabeceras referrer, una vulnerabilidad de seguridad crítica. Siempre usa POST con cuerpos JSON para la autenticación.

¿Puedo migrar gradualmente de los patrones de Swagger Petstore?

Sí. Soporta tanto los endpoints antiguos como los nuevos durante un período de transición. Añade advertencias de obsolescencia a los endpoints antiguos, actualiza la documentación y monitoriza el uso. Elimina los endpoints antiguos una vez que los clientes hayan migrado (típicamente de 6 a 12 meses).

¿Modern PetstoreAPI soporta GraphQL y gRPC?

Sí. A diferencia de Swagger Petstore (solo REST), Modern PetstoreAPI soporta múltiples protocolos: REST, GraphQL, gRPC, WebSocket, SSE, MQTT, Webhooks y MCP. Consulta la guía de protocolos para más detalles.

¿Cómo convenzo a mi equipo para que arregle el diseño de nuestra API?

Muéstrales los costos reales: confusión del desarrollador, errores del cliente, vulnerabilidades de seguridad y deuda técnica. Usa Apidog para demostrar las violaciones en tu API actual. Compara tu diseño con Modern PetstoreAPI y muestra las mejoras.

Practica el diseño de API en Apidog

Descubre una forma más fácil de construir y usar APIs

Registrarse gratisDescargar