Versionado de una ASP.NET Core 2 Web API sin usar Microsoft.AspNetCore.Mvc.Versioning

Hay una forma básica, sencilla y rápida de versionar nuestra Web API desarrollada en ASP.NET Core 2, y es lo que voy a tratar de enseñaros a hacer en esta entrada.

Es más, también os mostraré mi forma de versionar las APIs. Es algo que quiero compartir por si os sirve, y que he utilizado en los últimos años en algunos proyectos en los que he trabajado para Microsoft y para otras empresas.

Cuando preguntamos cómo versionar nuestras Web API en ASP.NET Core 2, muchos desarrolladores tienden a decirnos que debemos utilizar el paquete NuGet Microsoft.AspNetCore.Mvc.Versioning.

Esto es cierto, pero no siempre es necesario llegar aquí para cubrir nuestras necesidades.

Me explico.

Según el contexto en el que nos encontremos, puede suceder que no tengamos necesidad de versionar nuestras Apis utilizando Microsoft.AspNetCore.Mvc.Versioning y hacerlo de la forma tradicional a como lo hacíamos en ASP.NET, o hacerlo de una forma más simple, sencilla y directa, sin añadir complejidad a nuestro proyecto.

Si queremos ir un poco más allá como tengo pensado mostrar en otras entradas, entonces sí es recomendable, quizás, versionar de otra manera. Y ahí sí, Microsoft.AspNetCore.Mvc.Versioning podría sernos de interés.

El caso es que aquí voy a mostraros la forma básica (y muchas veces suficiente) de hacerlo.

Manos a la obra…

En primer lugar, iniciaremos Visual Studio 2017 (en mi caso, tengo instalada la versión 15.5.3).

Para elegir una plantilla válida, elegiré la sección Web y dentro de esta sección la plantilla ASP.NET Core Web Application.
Indicaré un nombre para la ruta en la que quiero guardar mi proyecto.

A continuación indicaré que quiero crear un proyecto de tipo Web API con ASP.NET Core 2.0.
No habilitaré autenticación ni nada más.

A continuación, crearé una clase que pondré en el raiz y que se llamará ApiRoute.cs.
Luego iremos a ella.
Simplemente, créala y continuemos.

Dentro de la carpeta Controllers, eliminaremos cualquier controlador que encontremos allí para dejar todo lo más limpio posible.

Una vez hecho esto, me iré al árbol de proyectos y crearé una carpeta V1 dentro de la carpeta Controllers y crearé un nuevo controlador.
Para ello, haré clic con el botón derecho del ratón sobre la carpeta V1 que he creado dentro de la carpeta Controllers y elegiré la opción Add => Controller.
Aparecerá una ventana en la que seleccionaré la opción de crear un controlador vacío.

Nos aparecerá ahora una ventana más pequeña en la que tendremos que indicar el nombre del controlador (reservando, según la convención, la palabra reservada Controller siempre al final del nombre del controlador).
En mi caso, he llamado mi controlador como FooController.

Si acudimos a la ventana del explorador de soluciones, veremos que la estructura de nuestro proyecto tendrá un aspecto similar al siguiente:

Llegados a este punto, tenemos la estructura base de nuestra Web API, pero todavía no hemos creado ninguna ruta ni nada por el estilo, y respecto al versionado, únicamente hemos creado una carpeta V1 dentro de Controllers, y hemos creado dentro un controlador nuevo.

Bien, ahora pensemos como queremos servir nuestra Web API.
En concreto, pensemos en la estructura general de llamada.

Imaginemos que tenemos pensado hacer tres métodos Get.

• Uno de ellos el general http://[server]/api/v1/foo.
• Otro que nos dé todo el contenido http://[server]/api/v1/foo/all.
• Y un tercer y último método al que pasemos un parámetro de entrada (un valor numérico por ejemplo) de forma que sea algo así como http://[server]/api/v1/foo/{id}.

Parece obvio, que la llamada general es compartida.
Es decir, la parte que se repite siempre es:

http://[server]/api/v1/foo

Bien, llevando este patrón hacia nuestra Web API, indicaré a continuación cómo lo hago yo (cada uno puede tener “su” forma de hacerlo, pero a mí esta forma me ha funcionado y el mantenimiento siempre me ha resultado muy sencillo).

Abriremos la clase ApiRoute y escribiremos el siguiente contenido:

public class ApiRoute
{

    /// <summary>
    /// <para>api/v1</para>
    /// </summary>
    private const string ApiVersionRoute = "api/v1";

    /// <summary>
    /// <para>api/v1/[controller]</para>
    /// </summary>
    public const string ControllerRoute = ApiVersionRoute + "/[controller]";

}

A continuación abriremos nuestro controlador y escribiremos este otro contenido:

public class FooController : Controller
{

    [HttpGet]
    [Route(ApiRoute.ControllerRoute)]
    public async Task<IActionResult> GetAsync() => Content(await GetDateTime() + " GetAsync");

    [HttpGet]
    [Route(ApiRoute.ControllerRoute + "/all")]
    public async Task<IActionResult> GetAllAsync() => Content(await GetDateTime() + " GetAllAsync");

    [HttpGet]
    [Route(ApiRoute.ControllerRoute + "/{id:int}")]
    public async Task<IActionResult> GetByIdAsync(int id) => Content(await GetDateTime() + $" and {id} GetByIdAsync");


    private async Task<string> GetDateTime()
    {
        return await Task.FromResult<string>(DateTime.UtcNow.ToString());
    }

}

Si ejecutamos nuestra Web API y la probamos con Fiddler u otro mecanismo que nos posibilite probar nuestra Web API, observaremos que se comporta tal y como queríamos.

De esta forma, tenemos nuestra Web API versionada, de forma rápida y sencilla.
Sin complicaciones.

Y en muchos proyectos nos resultará más que suficiente.

El mantenimiento sobre ApiRoute se hace de forma más sencilla que teniendo que ir a cada controlador y modificar cada método del controlador. Igual ocurre si queremos pasar de una V1 a una V2 o mantener una versión y crear otra nueva.

Si queremos hacer algún añadido, cambio, etc. un poco más rebuscado, igual tenemos que modificar ApiRoute, o bien tenemos que “fabricarnos” o ir a algo ya existente como podría ser Microsoft.AspNetCore.Mvc.Versioning.

El código fuente de esta implementación base de versionado, la encontrarás en este enlace de mi repositorio en GitHub.

¡Happy Coding!