Forem: Jhon Marmolejo

Versioning your API in .NET Core

Jhon Marmolejo — Thu, 08 Jul 2021 12:37:33 +0000

Hi,

Sometimes we need to change the behavior or payload of our APIs. For these cases it is recommended to have a versioning API.

Why do you need to versioning your API?

If your API is used by your websites, this is not a big problem because you can change these websites according the new requirements of our APIs.

On the other hand, if the API is consumed by mobile apps or third-party applications, its more complicated because you need release a new version of your apps and the users must install this new version in their mobile phones. So, in order to prevent errors and avoid breaking changes, it is important to have a versioning of your APIs.

How do we add versions for my API?

In order to versioning your API in .NET Core, you need to do the following steps:

In the API project, install the following nuget:

Install-Package Microsoft.AspNetCore.Mvc.Versioning

In the API project ConfigureServices()file method startup.cs, put the following code:

 services.AddApiVersioning(x =>
            {
                x.DefaultApiVersion = new ApiVersion(1, 0);
                x.AssumeDefaultVersionWhenUnspecified = true;
                x.ReportApiVersions = true;
                x.ApiVersionReader = new HeaderApiVersionReader("x-api-version");
            });

Where:
  x.DefaultApiVersion -> indicates the default version of the API.
  x.AssumeDefaultVersionWhenUnspecified-> indicates if the default version of the API will be used if in the request header we don't indicate the version of the API.
  x.ReportApiVersions -> indicates if we want to show in the response the available versions of the API.
  x.ApiVersionReader -> indicates how we are going to send the API version in the request.

In our case, we will send the version of our API through the Header, in this way, we avoid that the applications that use the API do not have to modify their calls. In addition, we add more security because we will send the version by header instead of querystring

Adding versioning to your controllers

In order to add the versioning to your controllers, you only need to add the following decorator in your class [ApiVersion("X.0")], where X.0 will be the version number of your API for this class. In case your controller does not have this decorator, the API version for this class will be the default version (in our case "1.0").

Controller without versioning

    [Route("api/[controller]")]
    [ApiController]
    public class DemoController : ControllerBase
    {
        [HttpGet]
        public IActionResult GetDemo()
        {
            return Content("Hola desde la versión por defecto");
        }
    }

Controller with versioning

    [Route("api/[controller]")]
    [ApiController]
    [ApiVersion("2.0")]
    public class DemoController : ControllerBase
    {
        [HttpGet]
        public IActionResult GetDemo()
        {
            return Content("Hola desde la versión 2");
        }
    }

Testing the versioning with Postman

Calling your API without API version in the Header

By default, the API will call the endpoint of the controller without specified version.

Calling your API with API version = 1.0 in the Header

The API will call the endpoint of the controller without specified version again, because we set the default version of the API equals to 1.0

Calling your API with API version = 2.0 in the Header

In this case, the API will return a different response because it goes to the controller that has this version.

Calling your API with a version that doesn't exist

If the API is called with a version that does not exist, it will return "by default" a BadRequest (400) indicating that it does not support this version number

In addition, the API will inform you of the available versions that you can use, because we set the value of ReportApiVersions = true in the configuration.

Finally, we already have our versioned api. You can find the github repository in this link:

https://github.com/jhonmarmolejo/NetCoreApiVersionDemo/tree/feature/ApiWithSwagger

See you next time!

Creando una API Gateway en .NET Core con Ocelot

Jhon Marmolejo — Wed, 30 Jun 2021 09:20:51 +0000

¿Tienes muchas APIS/microservicios y no quieres exponer los endpoints publicamente por temas de seguridad? ¿Tus apps externas necesitan hacer múltiples llamadas entre tus microservicios para poder obtener todo lo que necesitan? Un API Gateway te puede ayudar a solventar estos problemas.

En este video con @rogervinas te enseñaremos a como crear un API Gateway desde cero usando .Net Core y Ocelot y te explicaremos sus principales ventajas y como poder aplicarlo en tu trabajo.

YouTube:

0:00 Presentación
1:55 ¿Crees que repites mucho código en cada nuevo microservicio?
3:27 ¿Haces sufrir a tus frontends o quieres ser su backend favorito/a?
4:34 Flujo de llamadas sin Api Gateway
6:16 Flujo de llamadas con Api Gateway
7:28 ¿Que es una Api Gateway?
8:03 Api Gateways del mercado
9:07 ¡Demo time!
10:40 Añadimos Ocelot al proyecto
16:10 Rutas simples
22:28 Rutas con wildcard
28:42 Agregación
46:25 Autenticación
55:34 Autorización
1:00:35 Rate Limiting
1:03:12 Lógica Custom
1:11:15 Resumen

Y aquí tienes el código en Github (quitando la parte del bearer token en la configuración de ocelot)

jhonmarmolejo / apigatewayNetCoreOcelot

Hasta la próxima!

Desplegando tu API de .NET Core gratis en Heroku

Jhon Marmolejo — Thu, 01 Apr 2021 07:47:09 +0000

Cuando queremos compartir, testear y/o analizar el comportamiento de nuestra APIs de .NET Core en un entorno de pruebas diferente a local, tenemos muchos proveedores en la nube con opciones gratuitas como AWS, Windows Azure, pero en este artículo te enseñaré otra opción, mucho más fácil y rápida para realizar tu despliegue, Heroku.

Heroku es un PASS respaldado por Salesforce y permite a los desarrolladores desplegar sus aplicaciones de una forma fácil, gratuita (para aplicaciones de test o poco consumo), que permite el uso de diferentes lenguajes de programación y el despliegue se apoya internamente usando Github.

Para desplegar nuestra API en NET Core utilizaremos el siguiente repositorio el cual contiene una simple API desarollada en NET Core 3.1

jhonmarmolejo / NetCoreApiVersionDemo

A basic API in .NET CORE in order to show an API versioning

NetCoreApiVersionDemo

A basic API in .NET CORE 3.1 in order to show an API versioning

Requirements

SDK .NET CORE 3.1

Useful Links

Post Link

View on GitHub

Registrando tu API en Heroku

Antes de empezar debemos registrarnos en Heroku

https://signup.heroku.com/

Una vez registrado, debemos crear una nueva APP desde el dashboard

Ponemos el nombre a nuestra APP y seleccionamos la región en donde queremos desplegarla

Desplegando tu API

Clonamos el repositorio

git clone https://github.com/jhonmarmolejo/NetCoreApiVersionDemo.git

Nos situamos en el root de la solución, abrimos una consola de Powershell por ejemplo y ejecutamos el siguiente comando para restaurar todos los paquetes necesarios y ver que la solución compila correctamente

dotnet build

Entramos al folder que contiene el proyecto de la API. En nuestro caso ejecutamos el siguiente comando

cd MyApi

Dentro de este folder, ejecutamos el siguiente comando

heroku login

Luego de ejecutar este comando, tal como dice el mensaje, pulsamos cualquier letra (menos la letra q) para autenticarnos en Heroku. En este momento se abrirá el navegador para que tu puedas loguearte en Heroku

Damos click a "Log in" y ya estariamos logueados en Heroku para poder seguir el despliegue desde la consola

Una vez logueado, ejecutamos el siguiente comando para añadir acceso remoto a heroku

heroku git:remote -a adevintaapi

IMPORTANTE: Añadimos el buildpack necesario para poder desplegar nuestra API de net Core en Heroku

heroku buildpacks:set jincod/dotnetcore

Subimos el repositorio a heroku con el siguiente comando

git push heroku main

NOTA: Actualmente Heroku da error ejecutando este comando ya que necesita que tengamos seteado el stack de heroku-16 o heroku-18.

Para solucionar esto ejecutamos el siguiente comando y establecemos por defecto el stack de heroku-18

heroku stack:set heroku-18

Una vez solucionado esto, volvemos a ejecutar el comando

git push heroku main

Y si has seguido correctamente todas las instrucciones ya tenemos desplegada nuestra API en Heroku en la siguiente URL

https://adevintaapi.herokuapp.com/

Y para verificar que está desplegada correctamente, llamamos al único endpoint disponible que tiene esta API de ejemplo

https://adevintaapi.herokuapp.com/api/demo

Y como podemos ver, la api ya nos está devolviendo respuesta

Desplegando nuevos cambios

Si queremos modificar nuestra API y desplegar los nuevos cambios es tan simple como subir los cambios a github

git add .
git commit -m "New changes"
git push

Y una vez subido a github, ejecutar el comando para loguearnos en heroku

heroku login

Y luego lo subimos a heroku nuevamente ejecutando el siguiente comando

git push heroku main

Una vez ejecutado, volvemos a llamar al único endpoint disponible de la API y vemos que la respuesta ha cambiado

https://adevintaapi.herokuapp.com/api/demo

Hasta la próxima!

Documentando tu API versionada con Swagger

Jhon Marmolejo — Tue, 02 Feb 2021 11:54:02 +0000

En el post anterior vimos lo importante que es versionar nuestra API en .NET Core. En este post veremos como mostrar la documentación de esta API de manera visual usando Swagger.

Documentando tu API sin versionado

Si queremos documentar una API sin versionado debemos seguir los siguientes pasos:

1- Clonar el repositorio con la API versionada de la cual hablamos en el post anterior

git clone https://github.com/jhonmarmolejo/NetCoreApiVersionDemo.git

2- Abrir la solución y añadir los siguientes nugets al proyecto que contiene la API

Install-Package Swashbuckle.AspNetCore.SwaggerGen -Version 5.6.3
Install-Package Swashbuckle.AspNetCore.SwaggerUI -Version 5.6.3

3- Añadimos una nueva clase para extender la configuración de la API con la configuración de Swagger. A esta clase la llamaremos OpenApiConfiguration.cs

using System.IO;
using System.Linq;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

namespace MyApi.Extensions
{
    internal static class OpenApiConfiguration
    {
        public static IServiceCollection AddCustomOpenApi(this IServiceCollection services)
        {
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API Swagger", Version = "v1" });
                c.IncludeXmlComments(Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml"),true);
                c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
            });

            return services;
        }

        public static void UseCustomSwagger(this IApplicationBuilder app)
        {
            app.UseSwagger();
            app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API Swagger"); });
        }
    }
}

Donde en el método AddCustomApi configuramos lo siguiente:

El título y la versión de Open Api para la documentación.

c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API Swagger", Version = "v1" });

El path que usará Swagger para generar la documentación

c.IncludeXmlComments(Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml"),true);

NOTA: El path que usaremos aqui es del archivo de documentación que genera la API, para esto debemos ir a las propiedades de la API y marcar el check de XML Documentation file

Ya que nuestra API de ejemplo es versionada, tenemos que añadir este método para que Swagger resuelva conflictos en el caso de que encuentre endpoints duplicados.

 c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());

Y el método UseCustomSwagger nos permite indicar que usaremos la parte visual de Swagger.

4- En Startup.cs, llamamos a services.AddCustomOpenApi(); en el método
ConfigureServices

  public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            services.AddCustomOpenApi();
            ...
            ...
            ...
        }

Y llamamos a app.UseCustomSwagger en el método Configure

 public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseCustomSwagger();
            ...
            ...
            ...
        }

5- Ahora sólo queda ejecutar tu API e ir a la url /swagger/index.html

Documentando tu API con versionado

En el caso de que quedaremos documentar nuestra API versionada con Swagger, debemos hacer lo siguiente:

Seguir todos los pasos explicados anteriormente.
Añadir los siguientes filtros

SwaggerRemoveVersionFilter.cs -> quita el parámetro version de la operación

using System.Linq;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

namespace MyApi.Filters
{
    public class SwaggerRemoveVersionFilter : IOperationFilter
    {
        public void Apply(OpenApiOperation operation, OperationFilterContext context)
        {
            var versionParameter = operation.Parameters.FirstOrDefault(p => p.Name == "version");

            if (versionParameter != null)
            {
                operation.Parameters.Remove(versionParameter);
            }

        }
    }
}

SwaggerReplaceVersionFilter -> modifica el path que usará Swagger de acuerdo a la versión

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

namespace MyApi.Filters
{
    public class SwaggerReplaceVersionFilter : IDocumentFilter
    {
        public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
        {
            var paths = swaggerDoc.Paths;
            swaggerDoc.Paths = new OpenApiPaths();

            foreach (var path in paths)
            {
                var key = path.Key.Replace("v{version}", swaggerDoc.Info.Version);
                var value = path.Value;
                swaggerDoc.Paths.Add(key, value);
            }
        }
    }
}

3- En la clase OpenApiConfiguration.cs, modificar el método AddCustomOpenApi para llamar a los nuevos filtros al final.

public static IServiceCollection AddCustomOpenApi(this IServiceCollection services)
        {
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API Swagger v1", Version = "v1" });
                c.SwaggerDoc("v2", new OpenApiInfo { Title = "My API Swagger v2" , Version = "v2" });

                c.IncludeXmlComments(Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml"),true);

                c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
                c.OperationFilter<SwaggerRemoveVersionFilter>();
                c.DocumentFilter<SwaggerReplaceVersionFilter>();
            });

            return services;
        }

4- En la clase Startup.css, modificamos la configuración de OpenApi para usar el versionado por URL, esto lo hacemos para poder lanzar los ejemplos desde la misma interfaz que genera Swagger.

     services.AddApiVersioning(x =>
            {
                x.DefaultApiVersion = new ApiVersion(1, 0);
                x.AssumeDefaultVersionWhenUnspecified = true;
                x.ReportApiVersions = true;
            });

5- Por último vamos a los controllers y añadimos la siguiente cabecera en el inicio de la clase para indicar que usaremos el versionado por url

 [Route("api/v{version:apiVersion}/[controller]")]
 public class DemoController : ControllerBase
 {
    ...
    ...
    ...
 }

6- Ahora sólo queda ejecutar tu API e ir a la url /swagger/index.html donde podemos ver las diferentes versiones de la API

Y podemos lanzar las ejecuciones desde aquí validando que las respuestas son de las versiones que hemos seleccionado

Ejecutando la version 1 de la API

Ejecutando la version 2 de la API

El código de la API versionada con Swagger lo puedes encontrar en la rama feature/ApiWithSwagger en el siguiente repositorio

https://github.com/jhonmarmolejo/NetCoreApiVersionDemo/tree/feature/ApiWithSwagger

Hasta la próxima!!

Versionando tu API en .NET Core

Jhon Marmolejo — Thu, 03 Dec 2020 08:29:53 +0000

Muchas veces nos hemos topado con la necesidad de tener que cambiar el comportamiento o payload de un endpoint de nuestra API. Para estos casos, lo recomendable es tener un versionado de nuestras APIs.

¿Por qué versionar tu API?

Si tu API es usada por una web sobre la cual tienes control, no hay problema ya que tenemos poder para cambiar esta web acorde a los requerimientos de nuestra api.

Por otro lado, si esta API es consumida por una APP Mobile donde es necesario una actualización de la APP por parte del usuario, o la API es consumida por aplicaciones de terceros sobre la cual no tenemos control, es importante tener un versionado.

¿Cómo versionamos?

Para versionar tu API en .NET Core hacemos lo siguiente:

En el proyecto de la API, instalar el siguiente nuget:

Install-Package Microsoft.AspNetCore.Mvc.Versioning

En el método ConfigureServices() del archivo startup.cs del proyecto de la API, poner el siguiente código:

 services.AddApiVersioning(x =>
            {
                x.DefaultApiVersion = new ApiVersion(1, 0);
                x.AssumeDefaultVersionWhenUnspecified = true;
                x.ReportApiVersions = true;
                x.ApiVersionReader = new HeaderApiVersionReader("x-api-version");
            });

Donde:
  x.DefaultApiVersion -> indica la versión por defecto de la API.
  x.AssumeDefaultVersionWhenUnspecified -> indica si se usará la versión por defecto de la API cuando en el header del request no indiquemos la versión de la API que queremos usar.
  x.ReportApiVersions -> indica si queremos mostrar a los consumers las versiones disponibles de la API.
  x.ApiVersionReader -> indica la forma de como vamos a enviar la versión de API en el request.

En nuestro caso, enviaremos la versión de nuestra API por el Header, de esta manera evitamos que las aplicaciones que usen la API no tengan que modificar sus llamadas, además le añadimos un punto más de seguridad al enviarlo de esta manera en vez de por querystring por ejemplo.

Añadiendo el versionado a tus controllers

Para añadir el versionado a tus controllers, lo único que tiene que hacer es añadirle el decorado [ApiVersion("X.0")], donde X.0 será el número de versión que quieres dar a tu controller. En caso de que tu controller no tenga este decorado, la API asumirá que será la versión por defecto (en nuestro caso la "1.0").

Controller sin versionado

    [Route("api/[controller]")]
    [ApiController]
    public class DemoController : ControllerBase
    {
        [HttpGet]
        public IActionResult GetDemo()
        {
            return Content("Hola desde la versión por defecto");
        }
    }

Controller con versionado

    [Route("api/[controller]")]
    [ApiController]
    [ApiVersion("2.0")]
    public class DemoController : ControllerBase
    {
        [HttpGet]
        public IActionResult GetDemo()
        {
            return Content("Hola desde la versión 2");
        }
    }

Testeando el versionado con Postman

Llamando a tu API sin especificar la versión de la API en el Header

Por defecto cogerá el endpoint del controller que no se ha especificado la versión.

Llamando a tu API especificando la versión 1.0 de la API en el Header

Volverá a coger el endpoint del controller que no se ha especificado la versión ya que la versión 1.0 es igual al valor por defecto que hemos puesto en la configuración del versionado.

Llamando a tu API especificando la versión 2.0 de la API en el Header

En este caso devuelva una respuesta diferente ya que va al controller que tiene esta versión como decorado.

Llamando a tu API con una versión que no existe

Si se llama la API con una versión que no existe, esta devolverá "por defecto" un BadRequest(400) indicando que no soporta este número de versión

Además que en el header del response, la API te informará las versiones disponibles que puedes usar, siempre y cuando hallas establecido el valor de ReportApiVersions a true en la configuración

Y con esto ya tenemos nuestra api versionada. Dejo por aqui el repo de Github por si quieres testearlo.

https://github.com/jhonmarmolejo/NetCoreApiVersionDemo/tree/feature/ApiWithSwagger

Hasta la próxima!!