¿Por qué No Deberías Usar Verbos en URLs de APIs REST?

En resumen

Las URL de las API REST deben contener sustantivos (recursos), no verbos (acciones). Los métodos HTTP (GET, POST, PUT, DELETE) son los verbos. Usar verbos de acción como /getUser o /createOrder viola los principios REST, crea inconsistencia y hace que las API sean más difíciles de mantener. La PetstoreAPI Moderna utiliza URL orientadas a recursos en toda su extensión.

Introducción

Estás diseñando un endpoint de API para buscar mascotas por estado. Tu primer instinto podría ser: GET /findPetsByStatus?status=available. Es descriptivo, claro y te dice exactamente lo que hace. También es incorrecto.

Las API REST deben usar sustantivos en las URL, no verbos. El método HTTP es el verbo. GET /pets?status=available es el diseño correcto. La URL representa el recurso (mascotas), y el método representa la acción (obtener).

La antigua Swagger Petstore cometió este error con endpoints como /pet/findByStatus y /pet/findByTags. Estos verbos de acción en las URL violan los principios REST y crean problemas de mantenimiento. La PetstoreAPI Moderna lo soluciona utilizando URL orientadas a recursos de forma consistente.

En esta guía, aprenderás por qué los verbos no pertenecen a las URL REST, cómo diseñar endpoints orientados a recursos y cómo la PetstoreAPI Moderna implementa esto correctamente.

El Problema de los Verbos en las API REST

Los verbos de acción en las URL indican que estás pensando en términos de RPC (Remote Procedure Call), no en términos REST.

URL Estilo RPC (Incorrecto)

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

Estas URL describen acciones. Se leen como llamadas a funciones: createUser(), getUser(), sendEmail().

URL Estilo REST (Correcto)

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

Estas URL describen recursos. El método HTTP proporciona la acción.

Por qué esto Importa

Consistencia: Las URL REST siguen un patrón predecible. Una vez que conoces el nombre del recurso, conoces todos los endpoints:

• GET /pets - Listar mascotas
• POST /pets - Crear mascota
• GET /pets/{id} - Obtener mascota
• PUT /pets/{id} - Actualizar mascota
• DELETE /pets/{id} - Eliminar mascota

Con las URL basadas en verbos, cada endpoint es único. No hay un patrón a seguir.

Escalabilidad: A medida que tu API crece, las URL basadas en verbos se multiplican:

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

Las URL orientadas a recursos utilizan parámetros de consulta:

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

Un solo endpoint maneja todo el filtrado.

Por qué los Métodos HTTP son los Verbos

REST aprovecha los verbos incorporados de HTTP. No necesitas inventar los tuyos propios.

Los Métodos HTTP Mapean a Operaciones CRUD

POST   → Crear
GET    → Leer
PUT    → Actualizar (reemplazar)
PATCH  → Actualizar (parcial)
DELETE → Eliminar

Estos métodos tienen una semántica definida. GET es seguro e idempotente. POST crea recursos. DELETE los elimina.

Ejemplo: Gestión de Usuarios

Incorrecto (verbos en las URL):

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

Cada operación utiliza una URL diferente. El método HTTP no transmite significado.

Correcto (métodos HTTP como verbos):

POST /users           ← Crear usuario
GET /users/123        ← Obtener usuario
PUT /users/123        ← Actualizar usuario
DELETE /users/123     ← Eliminar usuario

La URL permanece igual. El método cambia.

Beneficios de Usar Métodos HTTP

1. Caché: Las solicitudes GET pueden ser almacenadas en caché. Los navegadores y proxies lo saben. Si utilizas POST /getUser, el almacenamiento en caché se rompe.

2. Idempotencia: PUT y DELETE son idempotentes. Llamarlos varias veces tiene el mismo efecto que llamarlos una vez. Esto es importante para la lógica de reintentos.

3. Seguridad: GET es seguro, no modifica el estado. Las herramientas y los rastreadores pueden llamar de forma segura a los endpoints GET.

4. Cumplimiento de Estándares: Los clientes HTTP, proxies y cachés entienden los métodos HTTP. No entienden tus verbos personalizados.

Ejemplos Reales de Swagger Petstore

La antigua Swagger Petstore incluye varios endpoints basados en verbos.

Ejemplo 1: Buscar Mascotas por Estado

Swagger Petstore (Incorrecto):

GET /pet/findByStatus?status=available

Problemas:

• findByStatus es una frase verbal
• Inconsistente con el endpoint /pet/{id}
• No se puede extender fácilmente (¿qué pasa con la búsqueda por otros criterios?)

PetstoreAPI Moderna (Correcto):

GET /pets?status=AVAILABLE

Beneficios:

• Orientada a recursos (/pets)
• Utiliza parámetros de consulta para filtrar
• Consistente con otros endpoints
• Fácil de extender: GET /pets?status=AVAILABLE&species=dog

Consulta la documentación REST de la PetstoreAPI Moderna para ver la implementación completa.

Ejemplo 2: Buscar Mascotas por Etiquetas

Swagger Petstore (Incorrecto):

GET /pet/findByTags?tags=tag1,tag2

PetstoreAPI Moderna (Correcto):

GET /pets?tags=friendly,trained

Ejemplo 3: Inicio de Sesión de Usuario

Swagger Petstore (Incorrecto):

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

Múltiples problemas:

• login es un verbo
• Uso de GET para autenticación (desastre de seguridad)
• Contraseñas en parámetros de consulta de URL

PetstoreAPI Moderna (Correcto):

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

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

Beneficios:

• Orientada a recursos (/auth)
• Método HTTP correcto (POST)
• Credenciales en el cuerpo de la solicitud, no en la URL
• Devuelve token JWT para solicitudes posteriores

Cómo la PetstoreAPI Moderna Soluciona Esto

La PetstoreAPI Moderna utiliza URL orientadas a recursos en toda su extensión.

Gestión de Mascotas

GET /pets                    ← Listar todas las mascotas
GET /pets?status=AVAILABLE   ← Filtrar por estado
GET /pets?species=dog        ← Filtrar por especie
GET /pets/{id}               ← Obtener mascota específica
POST /pets                   ← Crear nueva mascota
PUT /pets/{id}               ← Actualizar mascota
PATCH /pets/{id}             ← Actualización parcial
DELETE /pets/{id}            ← Eliminar mascota

Sin verbos. Solo recursos y métodos HTTP.

Gestión de Pedidos

GET /orders                  ← Listar pedidos
GET /orders/{id}             ← Obtener pedido
POST /orders                 ← Crear pedido
PUT /orders/{id}             ← Actualizar pedido
DELETE /orders/{id}          ← Cancelar pedido
GET /orders/{id}/items       ← Obtener artículos del pedido

Operaciones Complejas

Para operaciones que no se mapean limpiamente a CRUD, la PetstoreAPI Moderna utiliza subrecursos:

POST /orders/{id}/payment    ← Procesar pago para un pedido
POST /orders/{id}/shipment   ← Crear envío para un pedido
POST /pets/{id}/adoption     ← Iniciar proceso de adopción

Estas siguen siendo orientadas a recursos. /orders/{id}/payment representa el recurso de pago para un pedido.

Cuando los Verbos Parecen Necesarios

Algunas operaciones no encajan en el modelo CRUD. Aquí se explica cómo manejarlas sin verbos en las URL.

Operaciones de Búsqueda

Incorrecto:

GET /searchPets?query=labrador

Opción Correcta 1 (Parámetros de Consulta):

GET /pets?search=labrador

Opción Correcta 2 (Recurso de Búsqueda):

GET /pets/search?q=labrador

Opción Correcta 3 (Método QUERY):

QUERY /pets
Content-Type: application/json

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

La PetstoreAPI Moderna soporta los tres patrones dependiendo de la complejidad.

Cálculos

Incorrecto:

GET /calculateShipping?weight=10&destination=NY

Correcto:

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

El recurso son las "estimaciones de envío", no la acción de cálculo.

Operaciones por Lotes

Incorrecto:

POST /batchDeletePets

Correcto:

DELETE /pets?ids=1,2,3

O usar un recurso de lotes:

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

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

Acciones que Cambian el Estado

Incorrecto:

POST /activateUser
POST /deactivateUser

Correcto:

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

{
  "status": "ACTIVE"
}

Los cambios de estado son actualizaciones del recurso.

Prueba del Diseño de URL con Apidog

Apidog te ayuda a validar el diseño de API REST y a detectar el uso de verbos en las URL.

Importar PetstoreAPI Moderna

1. Importa la especificación OpenAPI de la PetstoreAPI Moderna
2. Apidog genera automáticamente casos de prueba
3. Revisa la estructura y el nombramiento de los endpoints

Verificar Verbos en las URL

Crea una regla de validación personalizada en Apidog:

// Check if URL contains common action verbs
// Comprueba si la URL contiene verbos de acción comunes
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.`);
  }
}

Probar la Consistencia de los Endpoints

Apidog puede verificar que los endpoints relacionados sigan patrones consistentes:

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

Todos utilizan el mismo recurso base (/pets).

Comparar con la PetstoreAPI Moderna

Usa la PetstoreAPI Moderna como referencia:

1. Importa tu API y la PetstoreAPI Moderna en Apidog
2. Compara las estructuras de los endpoints lado a lado
3. Identifica inconsistencias y uso de verbos
4. Refactoriza tu API para que coincida con los principios REST

Estrategias de Migración

Si tienes una API existente con verbos en las URL, aquí te explicamos cómo migrar.

Estrategia 1: Versionado

Crea una nueva versión de la API con URL correctas:

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

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

Mantén la v1 para compatibilidad retroactiva, fomenta la migración a la v2.

Estrategia 2: Alias

Soporta temporalmente tanto las URL antiguas como las nuevas:

# Old URL (deprecated)
# URL Antigua (obsoleta)
GET /pet/findByStatus?status=available

# New URL (preferred)
# Nueva URL (preferida)
GET /pets?status=available

Devuelve advertencias de obsolescencia en las respuestas:

{
  "data": [...],
  "warnings": [
    {
      "code": "DEPRECATED_ENDPOINT",
      "message": "Este endpoint está obsoleto. Usa GET /pets?status=available en su lugar.",
      "sunset": "2027-01-01"
    }
  ]
}

Estrategia 3: Redirecciones

Usa redirecciones HTTP 301 para migraciones simples:

GET /pet/findByStatus?status=available
→ 301 Movido Permanentemente
Location: /pets?status=available

Esto funciona para solicitudes GET, pero no para POST, PUT o DELETE.

Conclusión

Las URL de las API REST deben contener sustantivos (recursos), no verbos (acciones). Los métodos HTTP proporcionan los verbos. Este principio crea API consistentes, escalables y fáciles de mantener.

La antigua Swagger Petstore violó esto con endpoints como /pet/findByStatus. La PetstoreAPI Moderna lo soluciona utilizando URL orientadas a recursos en toda su extensión: /pets?status=AVAILABLE.

Puntos clave:

• Usa sustantivos en las URL: /pets, /orders, /users
• Deja que los métodos HTTP sean los verbos: GET, POST, PUT, DELETE
• Usa parámetros de consulta para filtrar: /pets?status=available
• Para operaciones complejas, usa subrecursos: /orders/{id}/payment
• Prueba el diseño de tu API con Apidog para detectar el uso de verbos a tiempo

Consulta la documentación de la PetstoreAPI Moderna para ver ejemplos completos de diseño de URL orientadas a recursos.

Preguntas Frecuentes

¿Puedo usar verbos alguna vez en las URL REST?

Rara vez. Si una operación realmente no encaja en el modelo de recursos (como /search o /login), un verbo podría ser aceptable. Pero el 95% de las veces, puedes modelarlo como un recurso.

¿Qué pasa con /login y /logout?

Estas son excepciones comunes. Muchas API usan /auth/login y /auth/logout. Alternativamente, modélalas como recursos: POST /sessions (inicio de sesión) y DELETE /sessions/{id} (cierre de sesión).

¿Cómo manejo consultas complejas?

Usa parámetros de consulta para filtrado simple: /pets?status=available&species=dog. Para consultas complejas, usa el método HTTP QUERY o un recurso de búsqueda: POST /pets/search.

¿Qué pasa si mi operación no se mapea a CRUD?

Modélala como un subrecurso. En lugar de POST /processPayment, usa POST /orders/{id}/payment. El pago es un recurso relacionado con el pedido.

¿Cómo pruebo si mis URL están orientadas a recursos?

Usa Apidog para importar tu especificación OpenAPI y buscar verbos en las URL. Compara la estructura de tu API con la PetstoreAPI Moderna como referencia.

¿Debo usar /pets/search o /pets?search=query?

Ambas son aceptables. /pets?search=query es más simple para búsquedas básicas. /pets/search o QUERY /pets funciona mejor para búsquedas complejas con múltiples parámetros.

¿Cómo migro de URL basadas en verbos?

Usa el versionado de API (/v2/pets en lugar de /v1/findPets), agrega advertencias de obsolescencia y da tiempo a los clientes para migrar. Consulta la sección Estrategias de Migración para más detalles.

¿La PetstoreAPI Moderna usa algún verbo en las URL?

La PetstoreAPI Moderna evita los verbos en las URL. Operaciones como búsqueda, filtrado y autenticación se modelan como recursos o usan parámetros de consulta. Consulta la documentación de la API REST para ver ejemplos.