martes, 5 de mayo de 2015

Api Management y Api DL (I) - Swagger, Swashbuckle, asp.net web Api

Estos días he estado investigando un poco sobre Api Management a raíz de un trabajo de análisis sobre varias herramientas de este tipo que hay en estos momentos en el mercado.

¿Qué es Api Management?

Es un sistema que facilita la publicación, control de versionado, distribución a subscriptores, monitorización tráfico de diferentes subscriptores y documentación de un conjunto de apis que maneja una compañía. Un sistema de api management por norma general también nos permite definir estrategias de cacheo, políticas de seguridad, analíticas.

Está claro que las api están revolucionando como las aplicaciones interactúan en los últimos tiempos y cada vez más compañías optan por estrategias de este tipo. Api Management nos proporciona un sistema centralizado para gobernar un ecosistema complejo de apis. Por tanto es normal que haya una gran variedad de fabricantes que han diseñado un producto que ofrece este tipo de servicios. Enumero algunos:

Azure, Akana, MuleSoft, Apigee, 3Scale, Ca Technologies, IBM Api Management, WSO2, Mashery, Layer7 (…)

La primera característica que queríamos valorar es como enfoca cada sistema la generación de documentación de uso de la api.

Quien habíamos trabajado con soap, recordamos el mítico wsdl que era un documento que servía a los consumidores de la api para saber que operaciones permite realizar el servicio y ver el modo de interactuar con cada operación. Además con soap existen herramientas para generar un cliente automáticamente en diferentes lenguajes. Bien, con la nueva tendencia REST están apareciendo estándares Api DL (Api definition Languaje) que equivalen a un wsdl en soap y/o frameworks que facilitan diseño, generación automática de documentación e integración de clientes. A continuación enumero algunos:

WADL, RAML, Swagger, Api Blue Print.

Quizás el más extendido en Swagger (o el que más me apetece probar). A continuación veremos cómo diseñar una api con Asp.Net y Swagger. Posteriormente la integraremos con algún producto de api management como el que ofrece Microsoft Azure.

En primer lugar creo una api sencilla con asp.net que se compone de un único recurso Alumno con el típico CRUD.
public class AlumnoController : ApiController
{
    // GET: api/Alumno
    public IHttpActionResult Get()
    {
        return Ok(MockData.Alumnos);
    }

    // GET: api/Alumno/5
    public IHttpActionResult Get(int id)
    {
        Alumno result = (from Alumno a in MockData.Alumnos where a.ID == id select a).FirstOrDefault();

        if (result != null)
            return Ok(result);
        else
            return NotFound();
            
    }

    // POST: api/Alumno
    public IHttpActionResult Post([FromBody]Alumno value)
    {
        MockData.Alumnos.Add(value);

        return Created(string.Format("alumno/{0}", value.ID),value);
    }

    // PUT: api/Alumno/5
    public IHttpActionResult Put(int id, [FromBody]Alumno value)
    {
        MockData.Alumnos[MockData.Alumnos.LastIndexOf(value)] = value;

        return Ok();
    }

    // DELETE: api/Alumno/5
    public IHttpActionResult Delete(int id)
    {
        Alumno toDelete = (from Alumno a in MockData.Alumnos where a.ID == id select a).FirstOrDefault();
        MockData.Alumnos.Remove(toDelete);

        return Ok();
    }
}
Este es el código que uso en clase Mockdata por si queréis seguir el mismo ejemplo, es una simple clase estática.
public static class MockData
{
    public static List Alumnos { get; set; }

    public static void InitData()
    {
        Alumnos = new List();
        Alumnos.Add(new Alumno() { ID = 1, Nombre = "Carlos" });
        Alumnos.Add(new Alumno() { ID = 2, Nombre = "Alba" });
    }
}
Hay varias opciones para integrar Swagger en asp.net web api, tras probar un poco me quedo con Swashbuckle. Para usar Swashbuckle en asp.net podemos añadirlo al proyecto mediante nuget.

Al añadir estos paquetes (swashbuckle.core y swashbuckle.ui) al proyecto veremos que se añade una clase de configuración al proyecto que nos servirá para controlar aspectos relacionados con la documentación de nuestra Api. Ahora a parte del apartado de documentación que ya viene incorporado en la plantilla de web api disponemos de otro apartado Swagger al que ya deberíamos poder acceder si vamos a http://apiUrl/Swagger.





En las imagenes si nos fijamos no compone bien el ejemplo de tipo de respuesta ni aparecen comentarios en las operaciones. Para que Swagger tenga en cuenta los comentarios y anotaciones que hacemos en el código de este tipo deberíamos activarlo en la configuración.
   c.IncludeXmlComments(GetXmlCommentsPath());
Por otro lado hemos de ir a propiedades del proyecto y en la pestaña compilar o build marcar la casilla "Xml Documentation File", veremos que automáticamente propone una ruta para el archivo de configuración. Copiala y se trata que te crees un método GetXmlComments() que devuelva la ruta completa de este archivo (el host también es necesario).

Ahora si vamos a la acción Get del controlador, introducimos comentarios en la firma del método y especificamos el tipo que se devuelve del siguiente modo:
    /// 
    /// Obtiene la lista completa de alumnos registrados.
    /// 
    /// Lista de alumnos registrados
    [ResponseType(typeof(List))]
    public IHttpActionResult Get()
    {
        return Ok(MockData.Alumnos);
    }
Si volvemos a mirar la ayuda vemos que aparecen reflejado.



No profundizo mucho más, si queréis más información sobre la integración de swashbuckle con asp.net web api podéis mirar su GitHub o bien este blog de donde he sacado los pasos para configurarlo. Si miras un poco el código comentado que hay en la clase de configuración de swagger te podrás hacer una idea de las posibilidades que ofrece para definir diferentes versiones, security... http://bitoftech.net/2014/08/25/asp-net-web-api-documentation-using-swagger/

En la segunda parte del post veremos la parte de api management donde usaré Azure como proveedor de este servicio. Como muchos otros fabricantes Azure soporta swagger para importar automáticamente la definición de la api que acabamos de crear, concretamente Azure soporta también WADL y no creo que tarden en añadir soporte para RAML (es una suposición mía, no he revisado doc oficial para ver si está previsto o no). Espero no tardar demasiado en acabar la segunda parte del post, últimamente con la llegada del buen tiempo cuesta un poco más dedicar el tiempo libre a la tecnología... es salir el sol y cambiar el portátil por la cerveza y olivas ;) jajjaja.

Hasta la próxima!! Recordar como siempre que puedes hacernos llegar a areaTIC todo comentario, critica, duda, aportación o lo que sea que será siempre bienvenido.