Cómo usar el control de versiones de API en ASP.NET Core

Al desarrollar API, debe tener en cuenta una cosa: el cambio es inevitable. Cuando su API haya llegado a un punto en el que necesite agregar más responsabilidades, debería considerar la posibilidad de crear versiones de su API. Por lo tanto, necesitará una estrategia de control de versiones.

Existen varios enfoques para el control de versiones de las API, y cada uno de ellos tiene sus pros y sus contras. Este artículo discutirá los desafíos del control de versiones de API y cómo puede trabajar con el paquete de control de versiones ASP.NET Core MVC de Microsoft para la versión de las API RESTful integradas en ASP.NET Core. Puede leer más sobre el control de versiones de API web en mi artículo anterior aquí. 

Crear un proyecto de API ASP.NET Core 3.1

En primer lugar, creemos un proyecto ASP.NET Core en Visual Studio. Suponiendo que Visual Studio 2019 esté instalado en su sistema, siga los pasos que se describen a continuación para crear un nuevo proyecto ASP.NET Core en Visual Studio.

  1. Inicie el IDE de Visual Studio.
  2. Haga clic en "Crear nuevo proyecto".
  3. En la ventana "Crear nuevo proyecto", seleccione "Aplicación web ASP.NET Core" de la lista de plantillas que se muestra.
  4. Haga clic en Siguiente.
  5. En la ventana "Configure su nuevo proyecto" que se muestra a continuación, especifique el nombre y la ubicación del nuevo proyecto.
  6. Haga clic en Crear.
  7. En la ventana "Crear nueva aplicación web ASP.NET Core", seleccione .NET Core como tiempo de ejecución y ASP.NET Core 3.1 (o posterior) en la lista desplegable en la parte superior. Usaré ASP.NET Core 3.1 aquí.
  8. Seleccione "API" como la plantilla de proyecto para crear una nueva aplicación ASP.NET Core API. 
  9. Asegúrese de que las casillas de verificación "Habilitar compatibilidad con Docker" y "Configurar para HTTPS" no estén marcadas, ya que no usaremos esas funciones aquí.
  10. Asegúrese de que la autenticación esté configurada como "Sin autenticación", ya que tampoco usaremos autenticación.
  11. Haga clic en Crear. 

Esto creará un nuevo proyecto de API ASP.NET Core en Visual Studio. Seleccione la carpeta de la solución Controladores en la ventana Explorador de soluciones y haga clic en "Agregar -> Controlador ..." para crear un nuevo controlador llamado DefaultController.

Reemplace el código fuente de la clase DefaultController con el siguiente código.

    [Ruta ("api / [controlador]")]

    [ApiController]

    clase pública DefaultController: ControllerBase

    {

        cadena [] autores = nueva cadena []

        {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

        [HttpGet]

        public IEnumerable Get ()

        {

            autores de retorno;

        }

    }

Usaremos este controlador en las secciones siguientes de este artículo.

Para implementar el control de versiones de API en ASP.NET Core, debe hacer lo siguiente:

  1. Instale el paquete de control de versiones de ASP.NET Core MVC.
  2. Configure el control de versiones de API en la clase Startup.
  3. Anote los controladores y las acciones con los atributos adecuados.

Instale el paquete de control de versiones de ASP.NET Core MVC

ASP.NET Core proporciona compatibilidad con el control de versiones de API listo para usar. Para aprovechar el control de versiones de la API, todo lo que necesita hacer es instalar el paquete Microsoft.AspNetCore.Mvc.Versioning de NuGet. Puede hacerlo a través del administrador de paquetes NuGet dentro del IDE de Visual Studio 2019 o ejecutando el siguiente comando en la consola del administrador de paquetes NuGet:

Paquete de instalación Microsoft.AspNetCore.Mvc.Versioning

Tenga en cuenta que si está utilizando ASP.NET Web API, debe agregar el paquete Microsoft.AspNet.WebApi.Versioning.

Configurar el control de versiones de API en ASP.NET Core

Ahora que el paquete necesario para el control de versiones de su API se ha instalado en su proyecto, puede configurar el control de versiones de API en el método ConfigureServices de la clase Startup. El siguiente fragmento de código ilustra cómo se puede lograr.

public void ConfigureServices (servicios IServiceCollection)

{

  services.AddControllers ();

  services.AddApiVersioning ();

}

Cuando realiza una solicitud Get a su API, se le presentará el error que se muestra en la Figura 1.

Para resolver este error, puede especificar la versión predeterminada al agregar los servicios de control de versiones de API al contenedor. También es posible que desee utilizar una versión predeterminada si no se especifica una versión en la solicitud. El siguiente fragmento de código muestra cómo puede establecer una versión predeterminada como 1.0 mediante la propiedad AssumeDefaultVersionWhenUnspecified si la información de la versión no está disponible en la solicitud.

services.AddApiVersioning (config =>

{

   config.DefaultApiVersion = new ApiVersion (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = true;

});

Observe cómo la versión principal y la versión secundaria se pasan al constructor de la clase ApiVersion en el momento de asignar la versión predeterminada. La propiedad AssumeDefaultVersionWhenUnspecified puede contener valores verdaderos o falsos. Si es cierto, la versión predeterminada especificada al configurar el control de versiones de la API se utilizará si no hay información de versión disponible.

El código fuente completo del método ConfigureServices se proporciona a continuación para su referencia.

public void ConfigureServices (servicios IServiceCollection)

{

    services.AddControllers ();

    services.AddApiVersioning (config =>

    {

         config.DefaultApiVersion = new ApiVersion (1, 0);

         config.AssumeDefaultVersionWhenUnspecified = true;

    });

}

Como no ha especificado ninguna información sobre la versión, todos los puntos finales tendrán la versión predeterminada 1.0.

Informar todas las versiones compatibles de su API

Es posible que desee que los clientes de la API conozcan todas las versiones compatibles. Para hacer esto, debe aprovechar la propiedad ReportApiVersions como se muestra en el fragmento de código que se muestra a continuación.

services.AddApiVersioning (config =>

{

  config.DefaultApiVersion = new ApiVersion (1, 0);

  config.AssumeDefaultVersionWhenUnspecified = true;

  config.ReportApiVersions = true;

});

Usar versiones en el controlador y métodos de acción

Ahora agreguemos algunas versiones compatibles a nuestro controlador usando atributos como se muestra en el fragmento de código que se muestra a continuación.

    [Ruta ("api / [controlador]")]

    [ApiController]

    [ApiVersion ("1.0")]

    [ApiVersion ("1.1")]

    [ApiVersion ("2.0")]

    clase pública DefaultController: ControllerBase

    {

        cadena [] autores = nueva cadena []

        {"Joydip Kanjilal", "Steve Smith", "Anand John"};

        [HttpGet]

        public IEnumerable Get ()

        {

            autores de retorno;

        }

    }

Cuando realiza una solicitud Get desde un cliente HTTP como Postman, así es como se informarán las versiones.

También puede informar sobre las versiones obsoletas. Para hacer esto, debe pasar un parámetro adicional al método ApiVersion como se muestra en el fragmento de código que se proporciona a continuación.

[ApiVersion ("1.0", Obsoleto = verdadero)]

Asignar a una versión específica de un método de acción

Hay otro atributo importante llamado MapToApiVersion. Puede usarlo para asignar una versión específica de un método de acción. El siguiente fragmento de código muestra cómo se puede lograr.

[HttpGet ("{id}")]

[MapToApiVersion ("2.0")]

cadena pública Get (int id)

{

   devolver autores [id];

}

Ejemplo completo de control de versiones de API en ASP.NET Core

Aquí está el código fuente completo del DefaultController para su referencia.

[Ruta ("api / [controlador]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

[ApiVersion ("2.0")]

clase pública DefaultController: ControllerBase

{

  cadena [] autores = nueva cadena []

  {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

  [HttpGet]

  public IEnumerable Get ()

  {

      autores de retorno;

  }

  [HttpGet ("{id}")]

  [MapToApiVersion ("2.0")]

  cadena pública Get (int id)

  {

     devolver autores [id];

  }

}

Estrategias de control de versiones de API en ASP.NET Core

Hay varias formas en las que puede versionar su API en ASP.NET Core. En esta sección exploraremos cada uno de ellos.

Pasar información de versión como parámetros QueryString

En este caso, normalmente pasará la información de la versión como parte de la cadena de consulta como se muestra en la URL que se proporciona a continuación.

//localhost:25718/api/default?api-version=1.0

Pasar información de versión en los encabezados HTTP

Si va a pasar información de la versión en los encabezados HTTP, debe configurarlo en el método ConfigureServices como se muestra en el fragmento de código que se proporciona a continuación.

services.AddApiVersioning (config =>

{

   config.DefaultApiVersion = new ApiVersion (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = true;

   config.ReportApiVersions = true;

   config.ApiVersionReader = new HeaderApiVersionReader ("api-version");

});

Una vez que se ha configurado, puede invocar un método de acción perteneciente a una versión específica de la API como se muestra en la Figura 3.

Pasar información de la versión en la URL

Otro método más de pasar información de versión es pasar información de versión como parte de la ruta. Esta es la forma más sencilla de crear versiones de su API, pero hay ciertas salvedades. En primer lugar, si utiliza esta estrategia, sus clientes deberán actualizar la URL cada vez que se lance una nueva versión de la API. En consecuencia, este enfoque rompe un principio fundamental de REST que establece que la URL de un recurso en particular nunca debe cambiar.

Para implementar esta estrategia de control de versiones, debe especificar la información de ruta en su controlador como se muestra a continuación.

[Ruta ("api / v {versión: apiVersion} / [controlador]")]

La siguiente lista de códigos muestra cómo puede configurar esto en su clase de controlador.

[Ruta ("api / v {versión: apiVersion} / [controlador]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

clase pública DefaultController: ControllerBase

    {

        cadena [] autores = nueva cadena []

        {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

        [HttpGet]

        public IEnumerable Get ()

        {

            autores de retorno;

        }

        [HttpGet ("{id}")]

        [MapToApiVersion ("2.0")]

        cadena pública Get (int id)

        {

            devolver autores [id];

        }

    }

Así es como puede llamar al HTTP predeterminado para obtener el método de la clase DefaultController.

//localhost:25718/api/v1.0/default

Para invocar el otro método HTTP GET, es decir, el que acepta un parámetro, especifique lo siguiente en el navegador web o en un cliente HTTP como Postman.

//localhost:25718/api/v2.0/default/1

Dar de baja una o más versiones de su API

Suponga que tiene varias versiones de su API, pero le gustaría desaprobar una o más de ellas. Puede hacer esto fácilmente: solo necesita especificar la propiedad En desuso de la clase ApiVersionAttribute en verdadero como se muestra en el fragmento de código que se proporciona a continuación.

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1", Obsoleto = verdadero)]

[ApiVersion ("2.0")]

clase pública DefaultController: ControllerBase

{

     // Código habitual

}

El control de versiones de API en ASP.NET Core ahora es perfecto gracias a la introducción del paquete Microsoft.AspNetCore.Mvc.Versioning. Hay varias formas de versionar su API; solo necesita decidir la mejor estrategia en función de sus requisitos. También puede utilizar varios esquemas de control de versiones para su API. Esto agrega mucha flexibilidad ya que los clientes pueden elegir cualquiera de los esquemas de control de versiones admitidos.

Cómo hacer más en ASP.NET Core:

  • Cómo usar objetos de transferencia de datos en ASP.NET Core 3.1
  • Cómo manejar errores 404 en ASP.NET Core MVC
  • Cómo usar la inyección de dependencia en filtros de acción en ASP.NET Core 3.1
  • Cómo usar el patrón de opciones en ASP.NET Core
  • Cómo usar el enrutamiento de punto final en ASP.NET Core 3.0 MVC
  • Cómo exportar datos a Excel en ASP.NET Core 3.0
  • Cómo usar LoggerMessage en ASP.NET Core 3.0
  • Cómo enviar correos electrónicos en ASP.NET Core
  • Cómo registrar datos en SQL Server en ASP.NET Core
  • Cómo programar trabajos usando Quartz.NET en ASP.NET Core
  • Cómo devolver datos de ASP.NET Core Web API
  • Cómo formatear los datos de respuesta en ASP.NET Core
  • Cómo consumir una API web ASP.NET Core con RestSharp
  • Cómo realizar operaciones asíncronas usando Dapper
  • Cómo usar marcas de características en ASP.NET Core
  • Cómo usar el atributo FromServices en ASP.NET Core
  • Cómo trabajar con cookies en ASP.NET Core
  • Cómo trabajar con archivos estáticos en ASP.NET Core
  • Cómo utilizar Middleware de reescritura de URL en ASP.NET Core
  • Cómo implementar la limitación de velocidad en ASP.NET Core
  • Cómo usar Azure Application Insights en ASP.NET Core
  • Uso de funciones avanzadas de NLog en ASP.NET Core
  • Cómo manejar errores en ASP.NET Web API
  • Cómo implementar el manejo de excepciones global en ASP.NET Core MVC
  • Cómo manejar valores nulos en ASP.NET Core MVC
  • Control de versiones avanzado en ASP.NET Core Web API
  • Cómo trabajar con servicios de trabajador en ASP.NET Core
  • Cómo usar la API de protección de datos en ASP.NET Core
  • Cómo usar middleware condicional en ASP.NET Core
  • Cómo trabajar con el estado de la sesión en ASP.NET Core
  • Cómo escribir controladores eficientes en ASP.NET Core