PARTE I: DOMINA EL DISEÑO DE UNA API
PARTE II: ARQUITECTURAS Y CONTROLADORES API
LABORATORIOS ¡Aplica ya! : DISEÑO Y VARIANTES API CON INMEMORY Y SQL SERVER

Controlando las versiones API

   Después de esta lección

Aprenderás a:

  • Comprender la problemática de las versiones API
  • Identificar las alternativas de versionado API.

Cursos Institucionales.
El Aprendizaje Hecho Fácil. ¡Disfrútalo!

   Laboratorios ¡Aplica ya!


El material teórico de las lecciones se aplica en los videos tutoriales del curso.

Las APIs cambian…


De seguro ya habrás detectado que los servicios y contratos de una API no son estáticos. Estos cambiarán con el tiempo gracias a nuevos requerimientos y evolución de los procesos estratégicos de las organizaciones y las tecnologías a consumir. Analicemos el siguiente escenario hipotético por su frecuencia de aparición:

APIS - VERSIONADO - EASY TO MAKE 0En la ilustración existen varios clientes con distintas tecnología accediendo a los servicios API. Ahora se tienen nuevos requerimientos y ajustes solicitados por algunos clientes corporativos. Esto significa ¡cambios en el contrato original!.  Realizar contratos independientes para cada cliente no parece ser una solución práctica. Esto traería un complejo y desgastantes mantenimiento por cada contrato así la organización sea una Pymes.

Alternativas de versionado API


#1: Versión URI en el controlador
O también conocido como Segmento de Ruta URL. Cada vez que se modifica la API web o cambia el esquema de recursos, agrega un número de versión al URI para cada recurso. Los URI ya existentes deben seguir funcionando como antes y devolver los recursos conforme a su esquema original como se observa en la ilustración:

[ApiVersion( "2.0" )]
[Route( "api/v{version:apiVersion}/[controller]" )]
public class RegistroMatriculaController : Controller {
    public string Get() {...};
}
 
[ApiVersion( "3.0" )]
[ApiVersion( "4.0" )]
[Route( "api/v{version:apiVersion}/RegistroMatricula" )]
public class RegistroMatricula2Controller : Controller {
    [HttpGet]
    public string Get() {...};
 
    [HttpGet, MapToApiVersion( "3.0" )]
    public string GetV4() {...};
} 

Este mecanismo de control de versiones es muy sencillo, pero depende del servidor que enruta la solicitud al extremo adecuado. Sin embargo, puede volverse difícil de manejar dado que la API web madura a través de varias iteraciones y el servidor tiene que admitir un número de versiones diferentes.

#2: Versión de encabezado
Debemos implementar un encabezado personalizado que indica la versión del recurso. Este enfoque requiere que la aplicación cliente agregue el encabezado adecuado a las solicitudes, aunque el código que controla la solicitud de cliente puede usar un valor predeterminado (versión 1) si se omite el encabezado de versión. En .Net Core esto es posible con el siguiente código a implementar en ConfigureServices así: 

public void ConfigureServices( IServiceCollection services )
{
    services.AddMvc();
    services.AddApiVersioning(o => o.ApiVersionReader = 
    new HeaderApiVersionReader("api-version"));
} 
Así para la versión 1 y 2 de nuestra API tendríamos:
GET https://easytomake.net/RegistroMatriculas/3 HTTP/1.1
Custom-Header: api-version=1

GET https://easytomake/RegistroMatriculas/3 HTTP/1.1
Custom-Header: api-version=2 

#3: Versión en cadena de consulta
En lugar de proporcionar varios URI, puedes especificar la versión del recurso mediante un parámetro dentro de la cadena de consulta anexada a la solicitud HTTP.  Este enfoque tiene la ventaja semántica de que el mismo recurso siempre se recupera del mismo URI, pero depende del código que controla la solicitud para analizar la cadena de consulta y enviar la respuesta HTTP adecuada:

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

[ApiVersion( "3.1" )]
[Route( "api/ v{versión: apiVersion} / RegistroMatriculas" )]
public class RegistroMatriculas312Controller : Controller {
    [HttpGet]
    public string Get() {...};
}

// La Versión insertada en la cadena de consulta se vería así:
https://easytomake.net/RegistroMatriculas/rm-0213?version=3.1 

Cambio completo a nueva versión


APIS - VERSIONADO - NUEVA VERSION 1 - EASY TO MAKE 0Los anteriores ejemplo permiten llevar el control de las versiones con ajustes o nuevos requerimientos. Pero ¿y para nuevas versiones API?

En la ilustración encontramos un escenario de este caso. Los clientes desconocen la versión, algunos continuarán usando la versión antigua de acuerdo a su conveniencia.

APIS - VERSIONADO - NUEVA VERSION 2 - EASY TO MAKE 0

Ahora tenemos en el escenario de la ilustración a dos clientes consumiendo la nueva versión API. Para hacer posible una transición sin traumatismos al resto de los cliente, se deberá crear un anuncio en los encabezados indicando que existe una nueva versión y que la actual será descontinuada. Para esto podríamos usar el siguiente código:

[ApiVersion( "3.0" )]
[ApiVersion( "2.1", Deprecated = true )] 

En .Net Core especificaremos la propiedad Deprecated o en desuso de la clase ApiVersionAttribute como true. Esta información se entregará a todos los clientes que consumen los servicios API versión 2.1  y sabrán que pronto será descontinuada por la nueva versión v3

APLICA YA! - Easy To Make   EASY INTERACTIVO.  ¡Intentalo! Afina tus conocimientos.