Cómo nombrar endpoints REST

Fecha de publicación: 2025-07-15
ParcelTrack API design
Nombrar correctamente los endpoints en una API RESTful es una de las habilidades más importantes para construir software limpio, mantenible y comprensible. En este artículo te presento una guía práctica usando como ejemplo un microservicio diseñado para gestionar envíos de paquetes.

Principios generales

Algunas reglas que puedes seguir para nombrar tus rutas REST:
  • Usa sustantivos en plural para recursos (por ejemplo: /shipments).
  • Evita verbos en la URL, el método HTTP ya indica la acción.
  • Usa jerarquía para subrecursos: /shipments/:id/history.
  • Identificadores como :id van en el path, no como query params.
  • Usa kebab-case para la consistencia.

Recursos

Algunos recursos clave y sus rutas base:
  • /shipments: para los envíos.
  • /packages: si los paquetes se gestionan por separado.
  • /shipments/:id/status: para actualizar el estado.
  • /shipments/:id/history: para consultar el historial de estados.

Operaciones REST básicas

A continuación un resumen de los endpoints recomendados y sus métodos HTTP:
POST /shipments             # Crear nuevo envío
GET  /shipments             # Listar todos los envíos
GET  /shipments/:id         # Ver detalles de un envío
PATCH /shipments/:id/status # Cambiar el estado
GET  /shipments/:id/history # Ver historial del envío
Observa cómo las acciones como crear, consultar, actualizar estado están implícitas en el método HTTP y la estructura de la ruta.

Filtros y paginación

Si necesitas filtrar resultados (por estado o usuario) o agregar paginación, usa query params:
GET /shipments?userId=123&status=PENDING&page=0&size=10
Esto permite al consumidor de la API controlar el resultado de forma flexible sin alterar la ruta base.

Errores comunes

Aquí algunos ejemplos de malos nombres que deberías evitar:
  • /createShipment ❌ – el verbo sobra, usa POST /shipments
  • /updateStatus ❌ – poco claro y sin contexto
  • /getAllShipments ❌ – get no es necesario

Conclusión

Diseñar endpoints bien nombrados mejora la experiencia de desarrollo, reduce errores y facilita la colaboración entre equipos.