Un recurso es cualquier entidad de información que una API REST expone al mundo, y un endpoint es la dirección exacta donde puedes encontrar ese recurso.
El momento en que todo se vuelve confuso
Era martes por la mañana en las oficinas de una empresa de logística en Guadalajara. Andrea, desarrolladora con seis meses de experiencia, tenía frente a ella la documentación de una API de rastreo de paquetes. Había tres URLs distintas para obtener información de un mismo envío: /getPackage, /fetchPackageById y /packageData. Las tres hacían cosas parecidas, pero nadie en el equipo sabía cuál usar en cada caso. El proyecto se atrasó dos días por esa confusión.
El problema de Andrea no era técnico. Era de diseño. Y para entenderlo, necesitas conocer dos conceptos que forman la columna vertebral de cualquier API REST bien construida: los recursos y los endpoints.
Qué es un recurso en una API REST
Un recurso es una "cosa" que tu API puede manejar. Puede ser un producto, un usuario, una orden de compra, una factura o cualquier objeto de tu sistema. En REST, todo gira alrededor de recursos.
Piensa en el catálogo de Mercado Libre. Tiene millones de productos. Cada producto es un recurso. Cada usuario registrado es un recurso. Cada orden de compra completada es un recurso. Los recursos son sustantivos, no verbos. Esa distinción es crítica.
Un error muy común entre desarrolladores nuevos es nombrar los recursos con verbos: /obtenerProducto, /crearUsuario, /eliminarOrden. En REST, eso está mal. El verbo ya lo comunica el método HTTP que aprendiste en la lección anterior: GET, POST, PUT, DELETE. El recurso solo dice qué cosa estás manipulando, no qué acción haces con ella.
Qué es un endpoint
Un endpoint es la URL completa que combina la dirección base de la API con la ruta al recurso. Es el punto de acceso concreto donde ocurre la comunicación.
Mira este ejemplo. Si la API de FEMSA tiene como dirección base https://api.femsa.com, un endpoint podría verse así:
https://api.femsa.com/productos/7821
Aquí, /productos/7821 es la ruta al recurso. El 7821 es el identificador único del producto específico que quieres consultar. La URL completa, incluyendo el dominio, es el endpoint.
En la práctica, los desarrolladores usan los términos "ruta" y "endpoint" de forma intercambiable. Lo importante es entender que un endpoint = dirección base + ruta al recurso.
Cómo se diseñan URLs claras y coherentes
Aquí está el secreto que la documentación de Andrea no tenía: una API REST bien diseñada sigue convenciones predecibles. Cuando las conoces, puedes intuir cómo funciona una API incluso antes de leer su documentación.
La primera convención es usar sustantivos en plural para nombrar colecciones. No /producto, sino /productos. No /usuario, sino /usuarios. Esto indica que ese recurso existe en cantidad y que puedes listar todos o acceder a uno específico.
La segunda convención es usar identificadores en la URL para acceder a recursos individuales. Si quieres todos los productos de Liverpool, vas a /productos. Si quieres solo el producto con ID 4501, vas a /productos/4501.
La tercera convención es anidar recursos cuando existe una relación clara entre ellos. Por ejemplo, si quieres ver las reseñas de un producto específico de Liverpool, la URL sería:
/productos/4501/resenas
Eso es mucho más claro que /obtenerResenasDeProducto?id=4501. La estructura de la URL ya te dice todo: estás buscando las reseñas que pertenecen al producto 4501.
Un ejemplo completo: la API de pedidos de Bimbo
Imagina que Bimbo expone una API interna para gestionar pedidos de sus distribuidores. Así se verían los endpoints bien diseñados:
GET /pedidos → Lista todos los pedidos
GET /pedidos/1092 → Muestra el pedido con ID 1092
POST /pedidos → Crea un pedido nuevo
PUT /pedidos/1092 → Actualiza el pedido 1092
DELETE /pedidos/1092 → Elimina el pedido 1092
Observa algo fascinante: la URL /pedidos/1092 no cambia entre las cuatro operaciones. Lo que cambia es el método HTTP. GET para leer, POST para crear, PUT para actualizar, DELETE para borrar. El recurso siempre es el mismo. La acción la define el método.
Eso es exactamente lo que hacía mal la API de Andrea. Tenía URLs distintas para la misma entidad porque el diseñador mezcló verbos en las rutas. Una API REST madura usa una sola URL por recurso y múltiples métodos.
Ahora imagina que Bimbo quiere ver los productos dentro de un pedido específico. El endpoint anidado sería:
GET /pedidos/1092/productos
Eso lee perfectamente en voz alta: "obtén los productos del pedido 1092".
Cuándo no anidar recursos
Anidar tiene un límite. Las buenas prácticas de la industria recomiendan no superar dos niveles de anidamiento. Una URL como esta se vuelve difícil de mantener:
/distribuidores/5/regiones/12/almacenes/3/pedidos/1092/productos/8
Eso es ocho segmentos. Nadie quiere leer eso a las 11 de la noche cuando hay un bug en producción. Una regla práctica: si tu URL tiene más de tres niveles de anidamiento, reconsidera el diseño. Quizás el recurso más profundo merece su propio endpoint raíz, como /productos/8, y simplemente filtras por contexto con parámetros de consulta.
Estudios en equipos de desarrollo muestran que las APIs con URLs largas y complejas tardan hasta un 40% más en integrarse por parte de equipos externos. La claridad no es solo estética; es velocidad de entrega.
Recursos, versiones y el mundo real
Un detalle que verás constantemente en APIs profesionales como la del SAT o Mercado Libre es el número de versión en la URL:
https://api.mercadolibre.com/v1/items/MLM123456
El /v1/ indica que estás usando la versión 1 de esa API. Esto es importante porque cuando una API evoluciona, los recursos pueden cambiar. Versionar la URL protege a los clientes que ya usan la API antigua. No tienen que cambiar su código de inmediato solo porque la empresa actualizó sus servicios.
Mercado Libre tiene actualmente más de 300 endpoints documentados públicamente. Todos siguen esta estructura coherente: versión, recurso, identificador. Esa consistencia permite que miles de desarrolladores en México y América Latina integren la plataforma sin necesidad de soporte constante.
Los errores más comunes al diseñar endpoints
El primero ya lo mencionamos: usar verbos en lugar de sustantivos. /crearProducto está mal. /productos con método POST está bien.
El segundo error es mezclar singular y plural sin criterio. Si usas /producto en un endpoint y /usuarios en otro, el consumidor de tu API tendrá que memorizar cada caso. La coherencia importa más que la perfección gramatical.
El tercer error es ignorar la jerarquía. Cuando un recurso claramente pertenece a otro, anidarlos hace la API más intuitiva. Pero cuando la relación no es de pertenencia sino de asociación débil, es mejor usar parámetros de consulta. Por ejemplo, para buscar pedidos de una fecha específica:
GET /pedidos?fecha=2024-11-15
No tiene sentido crear un endpoint como /fechas/2024-11-15/pedidos. La fecha no es un recurso que posee pedidos; es un filtro sobre la colección de pedidos.
El regreso al martes de Andrea
Con estos conceptos claros, Andrea hubiera identificado el problema en minutos, no en días. Tres URLs distintas para el mismo paquete son una señal de que la API no sigue los principios REST. La solución era simple: un solo recurso /envios con su identificador único, y los métodos HTTP definen la acción.
Cuando el equipo de Andrea rediseñó esa API aplicando estas convenciones, la integración con otros sistemas pasó de tomar días a tomar horas. No porque usaran tecnología nueva. Sino porque el lenguaje de la API se volvió predecible.
Eso es el poder de los recursos y los endpoints bien diseñados: no tienes que leer toda la documentación para entender cómo funciona una API. La estructura de la URL ya te lo dice.