C# Academy · Lección

Estrategias de versionado de API

Versione mediante la URL, el header y la cadena de consulta.

Estrategias de versionado de API es una lección gratuita de C# Academy en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de C# Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de C# Academy incluye 4 lecciones en total.

¿Por qué versionar una API?

Una vez que los clientes dependen de su API, no puede romper su contrato. El versionado le permite publicar cambios incompatibles en una versión nueva mientras los clientes antiguos siguen funcionando con la anterior.

// v1 returns { name }
// v2 returns { firstName, lastName }  (breaking)

Versionado en la ruta de la URL

La estrategia más visible incluye la versión en la ruta. Es inequívoca y facilita el enrutamiento, la navegación y la caché.

GET /api/v1/products
GET /api/v2/products

Versionado mediante la cadena de consulta

La versión se envía como un parámetro de consulta. Las URL permanecen estables y, si falta el parámetro, se puede usar la versión más reciente o una versión fija por defecto.

GET /api/products?api-version=1.0
GET /api/products?api-version=2.0

Versionado mediante encabezados

Un encabezado de solicitud personalizado contiene la versión y mantiene limpia la URL. La desventaja es que no resulta visible en la barra de direcciones del navegador y es más difícil de probar manualmente.

GET /api/products
X-Api-Version: 2.0

Versionado mediante el tipo de medio

También se denomina negociación de contenido. La versión se incluye en el tipo de medio del encabezado Accept. Es la opción más RESTful, pero la menos fácil de descubrir.

GET /api/products
Accept: application/json;v=2.0

Comparar las estrategias

Cada estrategia equilibra la facilidad de descubrimiento y la limpieza de la URL:

Ruta de la URL: la más fácil de descubrir, pero sobrecarga las URL.
Cadena de consulta: URL estables y valores predeterminados sencillos.
Encabezado: URL limpias, pero oculto para los navegadores.
Tipo de medio: REST más puro, pero más difícil de usar.

// Many teams pick URL path for public APIs

Versionado semántico de las API

Las versiones de las API suelen ser solo de tipo mayor (v1, v2). Reserve las versiones menores para cambios aditivos y compatibles que los clientes antiguos puedan ignorar.

// v1.0 -> v1.1 : additive (safe)
// v1   -> v2   : breaking (new version)

Obsolescencia

No elimine nunca una versión antigua de forma abrupta. Márquela como obsoleta, anuncie una fecha de retirada y comuníquelo a los clientes mediante encabezados.

// Response header on a deprecated version:
// Sunset: Wed, 31 Dec 2026 23:59:59 GMT
// Deprecation: true

Versión predeterminada

Decida qué sucede cuando un cliente no envía ninguna versión. Algunas opciones habituales son asumir la más reciente, asumir v1 o rechazar la solicitud. Ser explícito evita sorpresas.

// Strategy: unversioned request -> treat as v1.0

Versionar lo adecuado

Versione el contrato (rutas y estructuras de solicitud y respuesta), no los detalles internos de implementación. Un endpoint v2 puede compartir la mayor parte de la lógica de negocio con v1.

// Same service, two thin controllers:
// ProductsV1Controller, ProductsV2Controller

Combinar estrategias

La biblioteca de versionado de ASP.NET Core puede leer la versión de varias fuentes a la vez, lo que permite a los clientes elegir la que les resulte más cómoda. A continuación configurará esta funcionalidad.

// Accept version from URL OR header OR query

Comprobación rápida

Compruebe que entiende las estrategias de versionado.

Resumen

Ha repasado las estrategias de versionado de API:

Ruta de la URL, cadena de consulta, encabezado y tipo de medio.
Cada una equilibra la facilidad de descubrimiento y la limpieza de la URL.
Versione el contrato, gestione la obsolescencia correctamente y defina una versión predeterminada.

Siguiente: configurar Asp.Versioning en ASP.NET Core.

Preguntas frecuentes

¿La lección «Estrategias de versionado de API» es gratis?

Sí — el texto completo de «Estrategias de versionado de API» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de C# Academy, actualiza a CoddyKit PRO. El curso de C# Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Estrategias de versionado de API»?

Versione mediante la URL, el header y la cadena de consulta. Practicas C# Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar C# Academy?

No se requiere experiencia previa. C# Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.

¿Cuánto tiempo toma la lección «Estrategias de versionado de API»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de C# Academy?

Sí. Cada lección de C# Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

← Volver a C# Academy