El Punto JS

Fecha de publicación: 2025-07-15

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 el envío 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:

http

1POST /shipments             # Crear nuevo envío
2GET  /shipments             # Listar todos los envíos
3GET  /shipments/:id         # Ver detalles de un envío
4PATCH /shipments/:id/status # Cambiar el estado
5GET  /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:

http

1GET /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 ❌ – el prefijo get es innecesario

Conclusión

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