Las buenas prácticas para diseñar una API REST son convenciones que hacen tu API predecible, fácil de usar y fácil de mantener a largo plazo.
Hace tres años, el equipo de ingeniería de una startup de logística en Guadalajara lanzó su primera API. Los endpoints se llamaban /obtenerPedido, /crearNuevoPedido y /eliminarPedidoDelSistema. Seis meses después, contrataron a dos desarrolladores nuevos. Esos desarrolladores tardaron dos semanas enteras en entender cómo usar la API internamente. Dos semanas perdidas, sin escribir una sola línea de negocio.
El problema no era la tecnología. Era el diseño.
Lo que separa una API profesional de una improvisada
Un estudio de Nordic APIs encontró que el 56% de los desarrolladores abandona una integración si la documentación o el diseño de la API es confuso. Más de la mitad. Eso significa clientes perdidos, proyectos cancelados y horas de soporte innecesario.
Las buenas prácticas no son reglas arbitrarias. Son el resultado de miles de equipos cometiendo los mismos errores y acordando soluciones comunes. Cuando sigues estas convenciones, cualquier desarrollador del mundo puede usar tu API sin necesitar una llamada de 30 minutos para entenderla.
Aquí están las más importantes.
Nombra tus recursos como sustantivos, nunca como verbos
Esta es la regla número uno y la más violada. Los endpoints de una API REST deben representar recursos, no acciones. Los recursos son cosas: productos, pedidos, usuarios, facturas.
Imagina que estás diseñando la API de Liverpool para gestionar su catálogo. El error más común es esto:
GET /obtenerProducto/123
POST /crearProducto
DELETE /eliminarProducto/123
El problema es que el verbo ya está en el método HTTP. GET ya significa "obtener". POST ya significa "crear". DELETE ya significa "eliminar". Repetir el verbo en la URL es redundante y confuso.
La versión correcta usa sustantivos en plural:
GET /productos/123
POST /productos
DELETE /productos/123
Simple, limpio y predecible. Cualquier desarrollador que vea GET /productos/123 sabe exactamente qué esperar, sin leer documentación.
Usa siempre plural: /pedidos, /usuarios, /facturas. No /pedido o /usuario. El plural es la convención universal en APIs REST maduras como la de Mercado Libre o Stripe.
Usa la jerarquía de recursos para relaciones
Cuando un recurso pertenece a otro, puedes expresar esa relación en la URL. Esto se llama recursos anidados.
Supón que FEMSA tiene una API para gestionar sus tiendas OXXO. Cada tienda tiene inventario. La relación se expresa así:
GET /tiendas/456/productos
GET /tiendas/456/productos/789
POST /tiendas/456/productos
Estas URLs te dicen algo real: "los productos del OXXO número 456". La jerarquía tiene sentido.
Ahora, una advertencia importante: no anides más de dos niveles. Si tu URL empieza a verse así /empresas/1/regiones/2/tiendas/3/productos/4/variantes/5, tienes un problema de diseño. En ese caso, aplana la estructura y usa parámetros de consulta.
Versiona tu API desde el primer día
Este es el error que más duele en retrospectiva. Imagina que Bimbo lanza una API sin versiones para sus distribuidores. Seis meses después, necesitan cambiar el formato de respuesta de /productos. Si no tienen versiones, rompen todos los sistemas de sus distribuidores al mismo tiempo.
La solución es versionar la API desde el inicio. Hay dos formas comunes:
En la URL (más común y recomendada para principiantes):
GET /v1/productos
GET /v2/productos
En el encabezado:
Accept: application/vnd.bimbo.v2+json
El versionado en la URL es más visible y fácil de probar con Postman o curl, que aprendiste en la lección anterior. Por eso la mayoría de las APIs mexicanas y globales lo usan.
La regla es simple: cuando hagas un cambio que rompe la compatibilidad anterior, sube la versión. Cuando solo agregues campos nuevos o endpoints nuevos, no es necesario.
Los códigos de estado HTTP no son opcionales
Ya los viste en lecciones anteriores, pero en el diseño de tu propia API son igual de críticos. Devolver siempre 200 OK aunque haya un error es uno de los errores más frustrantes que puede cometer un equipo.
Estas son las respuestas que debes usar correctamente:
Cuando creas un recurso nuevo con POST, devuelve 201 Created, no 200. Cuando el cliente pide algo que no existe, devuelve 404 Not Found. Cuando los datos enviados son incorrectos, devuelve 400 Bad Request con un mensaje claro. Cuando el usuario no tiene permiso, devuelve 403 Forbidden.
Además, devuelve siempre un cuerpo JSON con información útil en los errores. Por ejemplo:
{
"error": "producto_no_encontrado",
"mensaje": "El producto con ID 789 no existe en el catálogo.",
"codigo": 404
}
Este formato le da al desarrollador tres cosas: un código de error interno para manejar en código, un mensaje legible para depurar y el código HTTP para confirmación. Los mejores equipos son consistentes: siempre el mismo formato de error en toda la API.
Documenta con ejemplos reales, no con descripciones abstractas
Una API sin documentación es como una tienda sin letrero. Puede que tenga los mejores productos adentro, pero nadie va a entrar.
La herramienta estándar de la industria es OpenAPI (antes llamada Swagger). Te permite describir tu API en un archivo YAML o JSON, y automáticamente genera una interfaz interactiva donde cualquier desarrollador puede probar los endpoints desde el navegador.
Pero la tecnología no es lo más importante. Lo más importante es el contenido. Una buena documentación incluye siempre tres cosas: el propósito del endpoint, un ejemplo real de petición con datos mexicanos concretos, y un ejemplo real de respuesta.
Mal ejemplo de documentación:
GET /pedidos/{id}— Devuelve un pedido.
Buen ejemplo de documentación:
GET /pedidos/10023— Devuelve los detalles del pedido número 10023, incluyendo productos, dirección de entrega en Ciudad de México y total en pesos. Respuesta de ejemplo:{"id": 10023, "total": "$1,850", "status": "enviado"}
La diferencia es enorme. El segundo ejemplo le ahorra al desarrollador 20 minutos de prueba y error.
Errores comunes que debes evitar
El primero ya lo vimos: usar verbos en los endpoints. El segundo error muy común es ignorar los filtros y la paginación.
Si tu endpoint /pedidos devuelve los 500,000 pedidos de un año completo en una sola respuesta, tu servidor va a colapsar. La solución es implementar paginación desde el inicio:
GET /pedidos?pagina=1&limite=50
GET /pedidos?pagina=2&limite=50
Y también filtros:
GET /pedidos?status=enviado&ciudad=monterrey
Estos parámetros de consulta son la forma estándar de filtrar y paginar. No crees endpoints separados como /pedidosEnviados o /pedidosDeMonterrey. Eso contamina tu API con docenas de rutas innecesarias.
El tercer error común es no usar HTTPS. Toda API que maneje datos reales debe funcionar sobre HTTPS, no HTTP. En México, el SAT y el IMSS requieren comunicaciones cifradas en cualquier sistema que maneje datos fiscales o laborales. HTTPS no es opcional en producción.
El regreso a Guadalajara
El equipo de logística de Guadalajara rediseñó su API después de esas dos semanas perdidas. Renombraron todos sus endpoints a sustantivos en plural, agregaron versiones desde /v1/, documentaron con ejemplos reales usando datos de envíos en Jalisco y CDMX, e implementaron paginación en sus listas.
Los dos desarrolladores nuevos que llegaron seis meses después tardaron media tarde en integrarse. No dos semanas. Media tarde.
Eso es lo que hace un buen diseño: desaparece. Cuando una API está bien diseñada, nadie la nota. Solo funciona. Y eso, en el mundo del desarrollo de software, es el mayor cumplido posible.