Jorge Saavedraapi-restbuenas-practicasdiseno-de-apihttp
Todos hemos visto APIs con rutas como
/getAllUsers, /createNewOrder o /updateUserStatus. A primera vista parecen descriptivas, pero en realidad van en contra de las convenciones que REST ya tiene resueltas. Cuando pones un verbo en la URL, estas duplicando informacion que el metodo HTTP ya comunica. Y esa redundancia, con el tiempo, se convierte en inconsistencia.Un buen nombrado de endpoints hace que tu API se documente sola. Cualquier desarrollador que vea
GET /users/123/orders entiende inmediatamente que esta obteniendo las ordenes del usuario 123. No necesita leer documentacion adicional, no necesita preguntarle a nadie. La ruta habla por si misma.Un mal nombrado, por otro lado, genera confusión, deuda tecnica y discusiones interminables en los pull requests. Si tu API tiene
/getOrders en un lado y /fetch-all-products en otro, cada nuevo endpoint se convierte en una decision arbitraria. Esta guia busca darte reglas claras para que eso no pase.La regla de oro
La regla mas importante es simple: usa sustantivos para las URLs, no verbos. El metodo HTTP ya es el verbo. Cada metodo tiene un significado semantico bien definido:
- GET = leer un recurso o una coleccion de recursos
- POST = crear un recurso nuevo
- PUT = reemplazar un recurso completo
- PATCH = actualizar parcialmente un recurso
- DELETE = eliminar un recurso
Cuando pones verbos como
create, get, update o remove en la URL, estas repitiendo lo que el metodo HTTP ya dice. Veamos la diferencia:http
# Mal: verbos en la URL (redundante)
POST /createUser
GET /getAllUsers
PUT /updateUser/123
DELETE /removeUser/123
# Bien: sustantivos + metodos HTTP
POST /users
GET /users
PUT /users/123
DELETE /users/123Observa como la version correcta es mas corta, mas limpia y mas predecible. Si alguien sabe que el recurso se llama
/users, automaticamente sabe como interactuar con el: GET para leer, POST para crear, PUT o PATCH para actualizar, DELETE para eliminar. No hay ambiguedad.Plural siempre
Usa siempre la forma plural para nombrar tus recursos:
/users, no /user. La razon es consistencia. La URL /users representa la coleccion completa de usuarios. Cuando agregas un identificador, /users/123, estas accediendo a un elemento especifico dentro de esa coleccion. El plural funciona en ambos casos de forma natural.Si usas singular para la coleccion y plural para los elementos (o viceversa), terminas con inconsistencias que confunden a quienes consumen tu API. Ademas, la mayoria de frameworks y herramientas de documentacion asumen el plural como convencion estandar. Mantenerlo simple te ahorra dolores de cabeza.
http
# Mal: mezclar singular y plural
GET /user # coleccion?
GET /user/123 # un usuario?
GET /users/123 # otro usuario?
# Bien: plural consistente
GET /users # coleccion de usuarios
GET /users/123 # usuario especifico
POST /users # crear un usuario nuevoJerarquia y subrecursos
Cuando un recurso pertenece a otro, la URL debe reflejar esa relacion de forma jerarquica. Las ordenes de un usuario, los items de una orden, los comentarios de un post: todos estos son subrecursos que se expresan naturalmente con rutas anidadas.
http
# Ordenes que pertenecen al usuario 123
GET /users/123/orders
# Items dentro de la orden 456
GET /orders/456/items
# Direcciones de envio del usuario 123
GET /users/123/addresses
# Comentarios del post 789
GET /posts/789/comments
POST /posts/789/commentsCuidado con la profundidad
Intenta no pasar de 2 o 3 niveles de anidacion. Una ruta como
/users/123/orders/456/items/789/reviews es dificil de leer y de mantener. Si llegas a ese punto, considera exponer el recurso de forma plana: GET /reviews?itemId=789 es mucho mas manejable.Query params vs path params
Esta es una distincion que muchos desarrolladores confunden al principio, pero es bastante directa una vez que entiendes el criterio. Los path params sirven para identificar un recurso especifico. Los query params sirven para filtrar, ordenar y paginar colecciones.
http
# Path params: identifican un recurso especifico
GET /users/123 # el usuario con ID 123
GET /orders/456 # la orden con ID 456
GET /users/123/orders/456 # la orden 456 del usuario 123
# Query params: filtran, ordenan y paginan
GET /users?status=active&sort=name&page=1&size=20
GET /orders?startDate=2025-01-01&endDate=2025-12-31
GET /products?category=electronics&minPrice=100&maxPrice=500La regla general: si el parametro identifica un recurso unico, va en el path. Si modifica la forma en que se presenta una coleccion (filtros, orden, paginacion), va como query param. Esto mantiene las URLs limpias y predecibles.
Casos especiales
No todo en una API se mapea limpiamente a operaciones CRUD. Hay acciones que no encajan en el modelo clasico de crear, leer, actualizar y eliminar. Para esos casos, existen convenciones que mantienen la coherencia sin romper los principios REST.
http
# Busqueda
GET /users/search?q=jorge&field=name
# Operaciones en lote (batch)
POST /users/batch
Body: [{"name": "Ana"}, {"name": "Luis"}, {"name": "Maria"}]
# Transiciones de estado
PATCH /orders/123/status
Body: {"status": "shipped"}
# Acciones que no son CRUD
POST /users/123/send-verification-email
POST /orders/456/cancelPara las transiciones de estado, PATCH es ideal porque estas modificando un solo campo del recurso. Para acciones como enviar un correo o cancelar una orden, se acepta usar un verbo en el ultimo segmento de la URL porque realmente es una accion, no un recurso. La clave es que estos casos sean la excepcion, no la regla.
Convenciones de formato
Mas alla de los nombres, hay convenciones de formato que ayudan a mantener tu API consistente y profesional. Estas son las mas importantes:
- kebab-case para URLs: usa
/user-profiles, no/userProfilesni/user_profiles - camelCase para campos JSON: usa
{"firstName": "Jorge"}, no{"first_name": "Jorge"} - Consistencia en todo el API: si un recurso se llama
/shipping-addresses, no lo llames/deliveryAddressesen otro endpoint - Versionado en la URL:
/api/v1/userspermite evolucionar tu API sin romper clientes existentes
http
# Formato correcto
GET /api/v1/user-profiles/123
GET /api/v1/shipping-addresses?userId=123
POST /api/v1/payment-methods
# Response body en camelCase
{
"id": 123,
"firstName": "Jorge",
"lastName": "Saavedra",
"emailAddress": "jorge@example.com",
"createdAt": "2025-03-15T10:30:00Z"
}Errores comunes
Estos son los patrones problematicos que veo con mas frecuencia en APIs reales, junto con la alternativa correcta y la razon del cambio:
http
# Verbos en la URL
POST /createUser -> POST /users
GET /fetchAllOrders -> GET /orders
PUT /modifyProduct/123 -> PUT /products/123
DELETE /removeItem/456 -> DELETE /items/456
# Singular en lugar de plural
GET /user -> GET /users
GET /product/123 -> GET /products/123
# Mezcla de formatos
GET /userProfiles -> GET /user-profiles
GET /shipping_addresses -> GET /shipping-addresses
# Rutas demasiado anidadas
GET /users/1/orders/2/items/3/reviews/4
-> GET /reviews/4
# Informacion sensible en la URL
GET /users?password=abc -> (nunca pases datos sensibles por URL)
# Rutas que exponen implementacion interna
GET /db/users/select-all -> GET /usersEl error mas comun
El error que veo con mas frecuencia es mezclar convenciones dentro del mismo proyecto. Un endpoint usa
/getUsers, otro usa /products, otro usa /fetch-orders. Cuando no hay una convencion clara desde el inicio, cada desarrollador inventa la suya y el resultado es una API inconsistente que nadie disfruta consumir. Define las reglas al principio del proyecto y documentalas en una guia de estilo.Codigos de respuesta HTTP
Un buen nombrado de endpoints va de la mano con el uso correcto de codigos de respuesta HTTP. No tiene sentido tener URLs impecables si despues respondes con 200 para todo, incluyendo los errores. Estos son los codigos que mas vas a usar:
http
# Respuestas exitosas
200 OK Solicitud procesada correctamente (GET, PUT, PATCH)
201 Created Recurso creado exitosamente (POST)
204 No Content Operacion exitosa sin cuerpo de respuesta (DELETE)
# Errores del cliente
400 Bad Request La solicitud tiene datos invalidos o mal formados
401 Unauthorized No se proporcionaron credenciales o son invalidas
403 Forbidden Las credenciales son validas pero no tiene permisos
404 Not Found El recurso solicitado no existe
409 Conflict La solicitud entra en conflicto con el estado actual
422 Unprocessable La solicitud es valida pero no se puede procesar
# Errores del servidor
500 Internal Error Algo salio mal en el servidor
503 Unavailable El servicio no esta disponible temporalmenteUn detalle importante:
401 Unauthorized y 403 Forbidden no son lo mismo. El 401 significa que no te has autenticado (no sabemos quien eres). El 403 significa que sabemos quien eres, pero no tienes permiso para hacer eso. Es una distincion sutil pero relevante para los consumidores de tu API.Sobre el 204 No Content
Cuando un DELETE es exitoso, lo ideal es responder con 204 y sin cuerpo en la respuesta. No necesitas devolver el objeto eliminado. El cliente ya sabe que recurso pidio eliminar. Lo mismo aplica para operaciones de actualizacion donde no necesitas confirmar los datos cambiados.
En resumen
Nombrar bien los endpoints de una API REST es como nombrar bien las variables: parece algo trivial hasta que estas depurando a las 2 de la manana tratando de entender que hace
/processDatao por que /getInfo a veces crea registros y a veces los actualiza.Las reglas son pocas y directas: usa sustantivos en plural, deja que el metodo HTTP sea el verbo, mantene la jerarquia plana, separa identificacion de filtrado, y sobre todo, se consistente. Una API bien nombrada no solo es mas facil de consumir, tambien es mas facil de mantener, documentar y evolucionar.
Toma estas convenciones como punto de partida, adaptalas a tu equipo si es necesario, pero lo mas importante es que todo el equipo siga las mismas reglas. La consistencia le gana a la perfeccion individual, siempre.
