Definition
Piensa en todo lo que interactúas en internet - tu perfil de Facebook, un vídeo de YouTube, un producto en Amazon, un tweet, el saldo de tu cuenta bancaria. Cada uno de estos es un “recurso” en términos de API. Un recurso es simplemente cualquier cosa que puede ser nombrada, identificada y manipulada a través de una API. Es el bloque de construcción fundamental de cómo pensamos y organizamos datos en la web.
El concepto viene de la arquitectura REST, donde todo se modela como recursos con direcciones únicas (URIs). La idea clave es que los recursos son sustantivos, no verbos. No tienes un endpoint de API llamado “getUser” o “deleteOrder” - en su lugar, tienes recursos llamados “users” y “orders” sobre los que realizas operaciones. Esto puede parecer una distinción sutil, pero cambia completamente cómo se diseñan las APIs y las hace mucho más intuitivas.
Los recursos pueden ser elementos individuales (un usuario específico con ID 123) o colecciones (todos los usuarios). Pueden ser anidados (todos los pedidos pertenecientes al usuario 123) o relacionados (las reseñas del producto 456). El mismo recurso puede tener diferentes representaciones - JSON para tu app móvil, XML para un sistema legacy, HTML para un navegador. Lo que hace que algo sea un recurso es que tiene identidad, estado y una interfaz uniforme para la interacción.
Example
Plataforma de Redes Sociales: En Twitter/X, los recursos están en todas partes. Tu perfil (/users/johndoe) es un recurso. Cada tweet (/tweets/1234567890) es un recurso. Tus seguidores (/users/johndoe/followers) son un recurso de colección. Cuando das like a un tweet, estás creando un nuevo recurso (/tweets/1234567890/likes). El timeline que ves (/users/johndoe/timeline) también es un recurso - una colección de tweets generada dinámicamente. Incluso conceptos abstractos como trending topics (/trends) se modelan como recursos.
Sistema E-commerce: La API de Amazon probablemente tiene docenas de tipos de recursos. Productos (/products/B08N5WRWNW), reseñas de productos (/products/B08N5WRWNW/reviews), carritos de compra (/carts/current), pedidos (/orders/111-2222222-3333333), listas de deseos (/wishlists/abc123), y seguimiento de envíos (/shipments/TBA123456789). Cada recurso tiene su propio ciclo de vida - un carrito se convierte en pedido, un pedido genera envíos, los envíos actualizan su estado con el tiempo.
API Bancaria: Tu cuenta bancaria (/accounts/1234567890) es un recurso con un saldo actual. Las transacciones (/accounts/1234567890/transactions) son un recurso de colección que crece con el tiempo. Cada transacción (/transactions/TXN123) es en sí misma un recurso con detalles como importe, comercio y timestamp. Las transferencias (/transfers/TRF456) son recursos que representan movimiento de dinero entre cuentas. Incluso los pagos programados (/scheduled-payments/SP789) son recursos que pueden crearse, modificarse o cancelarse.
Sistema de Gestión de Contenidos: En WordPress o sistemas similares, posts (/posts/hello-world), páginas (/pages/about), archivos multimedia (/media/image-123.jpg), categorías (/categories/technology), tags (/tags/api), y comentarios (/posts/hello-world/comments) son todos recursos. Usuarios (/users/admin), roles (/roles/editor), e incluso configuraciones (/settings/site-title) también son recursos.
Plataforma IoT: En un sistema de hogar inteligente, cada dispositivo es un recurso - tu termostato (/devices/thermostat-living-room), luces (/devices/light-bedroom-1), cerraduras (/devices/lock-front-door). Sus estados actuales son recursos (/devices/thermostat-living-room/state). Las reglas de automatización (/automations/night-mode) son recursos. Incluso eventos programados (/schedules/morning-routine) y registros de actividad (/devices/lock-front-door/history) son recursos.
Analogía
El Sistema de Archivador: Imagina un archivador masivo y perfectamente organizado. Cada cajón está etiquetado (como /customers o /invoices). Dentro de cada cajón hay carpetas (recursos individuales como /customers/acme-corp). Algunas carpetas contienen subcarpetas (/customers/acme-corp/contracts). Cada elemento tiene una etiqueta única que te dice exactamente dónde encontrarlo. Cuando necesitas algo, no dices “tráeme la cosa de ese lugar” - dices “tráeme /customers/acme-corp/contracts/2024-service-agreement”. Así es exactamente cómo funcionan los recursos en las APIs.
El Sistema de Biblioteca: Una biblioteca es una metáfora perfecta de recursos. Libros (/books/978-0-13-468599-1), DVDs (/media/dvd-12345), revistas (/periodicals/time-2024-01), e incluso miembros de la biblioteca (/members/M123456) son todos recursos. Cada uno tiene un identificador único (ISBN, número de catálogo, ID de miembro). Puedes consultar el estado de cualquier recurso, tomarlo prestado, devolverlo o reservarlo. El catálogo de la biblioteca es en sí mismo un recurso de colección. La lista de espera para un libro popular es un recurso.
El Modelo Inmobiliario: Piensa en los recursos como propiedades inmobiliarias. Cada propiedad (/properties/123-main-street) tiene una dirección única. Las propiedades tienen atributos (habitaciones, metros cuadrados, precio) que pueden cambiar con el tiempo. Pertenecen a colecciones (/properties?city=madrid). Tienen recursos relacionados - fotos (/properties/123-main-street/photos), informes de inspección (/properties/123-main-street/inspections), historial de precios (/properties/123-main-street/price-history).
La Colección del Museo: La colección de un museo demuestra los recursos perfectamente. Cada obra de arte (/artworks/mona-lisa) es un recurso con atributos (artista, año, técnica, dimensiones). El artista (/artists/leonardo-da-vinci) es un recurso relacionado. Las exposiciones (/exhibitions/renaissance-masters) son recursos de colección que agrupan obras. Audioguías (/artworks/mona-lisa/audio-guide) son recursos anidados.
Code Example
// Resources in a REST API
GET /products // Collection resource
GET /products/456 // Individual resource
GET /products/456/reviews // Nested resource
POST /products // Create new resource
PUT /products/456 // Update resource
DELETE /products/456 // Delete resource