Definition
Imagina que tienes una amiga llamada Sara. Podrías describir a Sara de muchas maneras - una fotografía, una biografía escrita, una grabación de voz, un avatar 3D, o incluso un dibujo de palitos. Sara misma no cambia, pero cómo la representas depende de quién pregunta y qué necesitan. En las APIs, una representación es exactamente esto - un formato o instantánea específica de un recurso en un momento particular.
Cuando solicitas un recurso de una API, no obtienes el recurso en sí (que es un concepto abstracto). Obtienes una representación de él - el estado actual del recurso empaquetado en un formato con el que puedes trabajar. El mismo recurso de perfil de usuario puede representarse como JSON cuando tu app móvil lo solicita, como XML cuando un sistema empresarial lo necesita, como HTML cuando se ve en un navegador, o como PDF cuando lo exportas. Los datos subyacentes son los mismos; solo cambia el empaquetado.
Este concepto es la “R” en REST (Representational State Transfer). Cuando haces una llamada a una API, el estado (datos) se transfiere como una representación. El cliente y el servidor negocian qué representación usar mediante negociación de contenido - envías una cabecera Accept: application/json, y el servidor responde con JSON. Esto desacopla el formato de los datos, haciendo las APIs increíblemente flexibles. Un solo endpoint puede servir a apps móviles, navegadores web, sistemas legacy y dispositivos IoT - cada uno recibiendo la representación que mejor entienden.
Example
Entrega de Contenido Multi-Plataforma: Cuando lees un artículo de noticias en El País, el mismo recurso de artículo tiene múltiples representaciones. Tu app móvil recibe una representación JSON con campos estructurados (titular, cuerpo, autor, array de imágenes). El sitio web renderiza una representación HTML con estilos y navegación. El crawler de Google recibe una representación HTML simplificada optimizada para indexación. Los lectores RSS obtienen una representación XML en formato Atom. Apple News recibe una representación JSON en formato Apple News. Mismo artículo, cinco representaciones diferentes.
Formatos de Respuesta de API: La API de GitHub demuestra las representaciones perfectamente. Cuando solicitas un repositorio (GET /repos/facebook/react), puedes recibir JSON (por defecto para clientes de API), HTML (cuando se ve en navegador), o incluso una representación tarball/zipball para descargar el código. Los pull requests pueden representarse como JSON para acceso de API, como formato unified diff para herramientas de code review, o como archivos patch para aplicación directa.
Recursos de Imagen: Considera un recurso de foto de perfil. Existe como un recurso lógico pero tiene muchas representaciones: el PNG original en alta resolución, un JPEG comprimido para visualización web, un thumbnail pequeño para listas, una versión WebP para navegadores modernos, un AVIF para compresión de vanguardia, e incluso una cadena codificada en base64 para embedding inline. CDNs de imágenes como Cloudinary o Imgix generan representaciones dinámicamente basándose en parámetros de query - mismo recurso de imagen, cientos de representaciones posibles.
Datos Financieros: Un recurso de cotización de acciones puede representarse diferentemente según las necesidades. Un sistema de trading en tiempo real podría obtener una representación binaria optimizada para velocidad. Una app móvil recibe JSON con precio, cambio, volumen. Una integración con hoja de cálculo obtiene formato CSV. Un terminal Bloomberg recibe un formato propietario. Herramientas de análisis histórico podrían obtener JSON de series temporales con cientos de puntos de datos.
Recursos de Documento: Un documento en Google Docs es un único recurso con muchas representaciones. Puedes exportarlo como PDF (para imprimir), como DOCX (para usuarios de Word), como ODT (para LibreOffice), como HTML (para publicación web), como texto plano (para procesamiento), o como EPUB (para e-readers). El recurso del documento permanece igual; las representaciones se generan bajo demanda.
Analogía
El Guía Turístico Multilingüe: Imagina un guía turístico en el Museo del Prado frente a Las Meninas. La pintura (recurso) es una cosa, pero el guía puede representarla diferentemente para cada grupo - en español para locales, inglés para americanos, mandarín para turistas chinos, lengua de signos para visitantes sordos, o una descripción en Braille para visitantes ciegos. Misma pintura, misma información, diferentes representaciones adaptadas a las necesidades de cada audiencia.
La Receta en Diferentes Formatos: Una receta de tarta de chocolate es un recurso, pero puede representarse de muchas maneras. Un libro de cocina impreso la muestra con fotos bonitas y tipografía. Un sitio web de cocina la muestra con vídeos y fotos paso a paso. Un altavoz inteligente la lee en voz alta paso a paso. Una app de planificación de comidas la muestra como datos estructurados (lista de ingredientes, info nutricional, tiempo de preparación). Una app de compras representa solo los ingredientes como una lista de verificación. La receta no cambia - solo cómo se empaqueta para el consumo.
La Partitura Musical: Una sinfonía es un recurso musical, pero sus representaciones varían enormemente. La partitura original escrita a mano es una representación. Una versión impresa de partitura es otra. Un archivo MIDI la representa digitalmente. Un MP3 es una representación de audio. Una visualización musical la representa visualmente. La partitura anotada del director añade marcas de interpretación. La parte de cada músico extrae solo la representación de su instrumento.
El Plano vs. El Edificio: Un plano arquitectónico es una representación de un diseño de edificio (el recurso). El mismo diseño puede representarse como planos 2D, imágenes renderizadas 3D, recorridos en VR, archivos CAD, listas de materiales, cronogramas de construcción, o maquetas a escala. Los contratistas necesitan dibujos técnicos detallados; los clientes prefieren renders fotorrealistas; los urbanistas quieren planos del solar.
Code Example
// Same resource, different representations
GET /users/123
Accept: application/json
// Returns: {"id": 123, "name": "Alice"}
GET /users/123
Accept: application/xml
// Returns: <user><id>123</id><name>Alice</name></user>