Definition
Cuando las APIs evolucionan, necesitas una forma de decirle al servidor qué versión de los datos quieres - y hay una manera sorprendentemente elegante de hacerlo usando un mecanismo que HTTP ha tenido desde siempre. El versionado por tipo de medio pone la versión de la API directamente dentro de la cabecera Accept, la misma cabecera que tu navegador usa para decirle a los servidores si quiere HTML, JSON o imágenes.
En lugar de poner números de versión en la URL (como /api/v1/users) o parámetros de consulta (?version=2), el versionado por tipo de medio usa tipos de contenido personalizados. Envías una cabecera como Accept: application/vnd.miempresa.v2+json que dice “Quiero la versión 2 de tu API, formateada como JSON.” El “vnd” significa “vendor” (proveedor) - es una señal de que este es un tipo de medio personalizado definido por una organización específica.
Este enfoque se considera el más “RESTful” porque usa el sistema de negociación de contenido incorporado en HTTP exactamente como fue diseñado. La URL permanece limpia y enfocada en identificar el recurso (/users/123), mientras que la versión se trata como un detalle sobre cómo quieres que ese recurso sea representado. Es como la diferencia entre pedir el “documento #123” (la URL) versus pedir “el documento #123, pero por favor dame la versión 2020 en formato PDF” (el tipo de medio). Esta separación hace que tus URLs sean atemporales - no necesitan cambiar cuando lanzas una nueva versión de la API.
Example
El versionado por tipo de medio es usado por algunas de las APIs más amigables para desarrolladores. Aquí es donde lo encontrarás:
La API de GitHub: GitHub es el ejemplo por excelencia del versionado por tipo de medio. Cuando llamas a su API, especificas Accept: application/vnd.github.v3+json para obtener la versión 3 de su API en formato JSON. Cuando GitHub lance la versión 4, puedes cambiar modificando solo esa cabecera - todas tus URLs permanecen iguales. GitHub incluso soporta solicitar características preview específicas con cabeceras como Accept: application/vnd.github.squirrel-girl-preview+json (sí, ese es un nombre real de preview para las reacciones).
La API de Stripe (enfoque híbrido): Aunque Stripe principalmente usa versionado basado en fechas en cabeceras, también soporta negociación de contenido para selección de formato. Este enfoque híbrido muestra cómo los conceptos de tipo de medio se mezclan con otras estrategias en el mundo real.
Sistemas Empresariales: Muchas APIs empresariales grandes usan versionado por tipo de medio porque encaja bien con service meshes y API gateways que pueden enrutar peticiones basándose en cabeceras. Un gateway puede enviar peticiones v1 a los servidores legacy y peticiones v2 a nuevos microservicios, todo transparente para el cliente.
Sistemas de Gestión Documental: Cuando recuperas documentos a través de APIs, los tipos de medio manejan naturalmente la pregunta “¿en qué formato lo quieres?” - metadatos JSON, descarga PDF, o vista previa HTML del mismo recurso de documento.
Analogía
El Menú del Restaurante con Idiomas: Imagina un restaurante donde el elemento del menú es el mismo (Recurso: “Plato #47”), pero puedes pedirlo descrito en diferentes idiomas y niveles de detalle. Le dices al camarero “Quiero el plato 47, en español, con todos los ingredientes detallados” - estás especificando la representación que quieres, no cambiando qué plato estás pidiendo. El versionado por tipo de medio funciona de forma similar: mismo recurso, diferentes formas de describirlo.
Las Versiones de Documentos Legales: Piensa en cómo los bufetes de abogados manejan las versiones de contratos. El acuerdo subyacente (el recurso) puede ser el mismo, pero los clientes pueden solicitar la revisión de 2022 con las cláusulas de responsabilidad actualizadas o el formato más simple de 2020. No creas un nuevo número de contrato para cada revisión - pides la versión que necesitas. Los tipos de medio funcionan igual.
El Mando Universal: Los mandos universales modernos pueden controlar cualquier televisor, pero tienes que decirles qué protocolo usar. El botón “encendido” (el recurso) es el mismo, pero el formato de señal cambia según el dispositivo. El versionado por tipo de medio es como decirle al mando “envía este comando usando el protocolo Samsung 2023” - mismo comando, representación adaptada.
La Calidad del Streaming de Música: Cuando haces streaming de música, estás solicitando la misma canción (recurso), pero los servicios te dejan elegir la calidad: calidad CD, alta resolución, o comprimida para móvil. No obtienes IDs de canción diferentes para diferentes calidades - especificas el formato que quieres. El versionado por tipo de medio trae este mismo concepto a los datos de API.
Code Example
// Media type versioning (GitHub style)
GET https://api.company.com/repositories/123
Accept: application/vnd.company.v1+json
GET https://api.company.com/repositories/123
Accept: application/vnd.company.v2+json
// With format negotiation
GET https://api.company.com/repositories/123
Accept: application/vnd.company.v2+xml
// Specific version with parameter
GET https://api.company.com/repositories/123
Accept: application/vnd.company+json; version=2
// Server response includes media type
[HTTP/1.1](https://reference.apios.info/es/terms/http-1-1/) 200 OK
Content-Type: application/vnd.company.v2+json; charset=utf-8
// Unsupported version
GET https://api.company.com/repositories/123
Accept: application/vnd.company.v5+json
HTTP/1.1 406 Not Acceptable
Content-Type: application/json
{
"error": "NotAcceptable",
"message": "API version 5 not available",
"supportedVersions": ["v1", "v2", "v3"]
}