Versionado de API en .NET Web API

El versionado de API es esencial cuando tu API evoluciona y se introducen cambios que podrían romper compatibilidad. Implementar versionado garantiza que los clientes existentes sigan funcionando mientras se añaden nuevas funcionalidades y mejoras. En Q2BSTUDIO, empresa especializada en desarrollo de software a medida, aplicaciones a medida, inteligencia artificial y ciberseguridad, ayudamos a diseñar APIs robustas y escalables que incorporan mejores prácticas de versionado y gestión del ciclo de vida.

Por qué versionar una API: backward compatibility para que clientes antiguos sigan funcionando; actualizaciones suaves que permiten introducir nuevos endpoints sin romper funcionalidad existente; comunicación clara para que los clientes sepan qué versión usan; y gestión de ciclo de vida que facilita deprecaciones graduales.

Paso 1 Añadir el paquete NuGet necesario ejecutar en terminal dotnet add package Microsoft.AspNetCore.Mvc.Versioning Este paquete permite versionar por query string, header o segmento de URL.

Paso 2 Configurar versionado en Program.cs ejemplo minimal usando la librería en span conteniendo código con entidades para los signos menor y mayor span>var builder = WebApplication.CreateBuilder(args); builder.Services.AddControllers(); builder.Services.AddApiVersioning(options => { options.AssumeDefaultVersionWhenUnspecified = true; options.DefaultApiVersion = new Microsoft.AspNetCore.Mvc.ApiVersion(1,0); options.ReportApiVersions = true; }); var app = builder.Build(); app.MapControllers(); app.Run();</span> Este fragmento habilita versionado por defecto y reporta versiones disponibles en las cabeceras de respuesta.

Paso 3 Crear un BaseApiController Un controlador base centraliza configuración, atributos y helpers comunes para controladores versionados. Ejemplo simplificado usar herencia para mantener el código DRY y consistente con respuestas que incluyen la versión solicitada.

Paso 4 Versionar controladores heredando de BaseApiController ejemplo span con entidades para mostrar atributos de versión span>[ApiVersion('1.0')] public class ProductsController : BaseApiController { [HttpGet] public IActionResult Get() => ApiResponse(new[] { 'Product 1', 'Product 2' }); } [ApiVersion('2.0')] public class ProductsV2Controller : BaseApiController { [HttpGet] public IActionResult Get() => ApiResponse(new[] { 'Product A', 'Product B', 'Product C' }); }</span> Esto mantiene el código limpio y centraliza la lógica del versionado.

Paso 5 Versionado por query string y cabeceras Ejemplo por query string GET /api/orders?api-version=1.0 o GET /api/orders?api-version=2.0 Para versionado por cabecera configurar ApiVersionReader en Program.cs options.ApiVersionReader = new HeaderApiVersionReader(x-api-version) y los clientes envían la cabecera x-api-version con el valor deseado. Esto facilita adaptar clientes y herramientas que prefieren headers en lugar de URL.

Paso 6 Deprecación de versiones marcar versiones antiguas como Deprecated y avisar en cabeceras para que los consumidores sepan que deben migrar a versiones posteriores. Ejemplo span>[ApiVersion('1.0', Deprecated = true)] public class OldController : BaseApiController { [HttpGet] public IActionResult Get() => ApiResponse('Esta versión está obsoleta'); }</span>

Paso 7 Integración con Swagger para APIs versionadas añadir múltiples SwaggerDoc en la configuración para exponer documentación separada por versión y usar UseSwaggerUI para registrar los endpoints de swagger v1 y v2. Esto ofrece a desarrolladores y a equipos de QA una vista clara de las APIs por versión.

Buenas prácticas adicionales incluir políticas claras de deprecación, pruebas automatizadas por versión, semver cuando aplique y considerar compatibilidad hacia atrás en contratos de datos. Combinar versionado por URL para cambios mayores y por cabecera o query para cambios menores suele ser una estrategia equilibrada.

En Q2BSTUDIO ofrecemos servicios completos para diseñar e implementar APIs versionadas y seguras como parte de soluciones de software a medida. Si buscas desarrollar aplicaciones a medida robustas y con buenas prácticas de arquitectura, visita nuestra página de desarrollo de aplicaciones y software a medida Desarrollo de aplicaciones y software multiplataforma. Además integramos capacidades de inteligencia artificial en APIs y soluciones empresariales; conoce nuestros servicios de inteligencia artificial para empresas en Inteligencia artificial.

Ofrecemos también servicios complementarios clave para el éxito de tus APIs y plataformas como ciberseguridad y pentesting, servicios cloud aws y azure, servicios de inteligencia de negocio y Power BI, automatización de procesos, agentes IA y consultoría en ia para empresas. Palabras clave para posicionamiento incluidas naturalmente en nuestras soluciones aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA y power bi.

Resumen usar un BaseApiController centraliza lógica común, mantiene controladores DRY y facilita la gestión del versionado. Combinado con versionado por URL, query string o headers y documentación Swagger obtienes una API flexible, mantenible y alineada con buenas prácticas de ingeniería de software. Contacta a Q2BSTUDIO para diseñar tu API y potenciarla con inteligencia artificial, ciberseguridad y despliegue en la nube.