Toolbox de desarrollo de APIs REST

  • Artigo

O también de desarrollo sobre APIs.

Ya no es ningún secreto que las APIs de hoy se construyen con la simplicidad de REST  y JSON.

Hay tal flexibilidad ya, que en todo lado encontramos herramientas muy apropiadas tanto para ayudarnos en el desarrollo de estas APIs, como para sus pruebas.

De los temas más acostumbrados hoy en día, es que la API reciba requests POST, donde los parámetros de ejecución vienen embebidos en un JSON que es transmitido dentro del content de dicho post.

Trabajando con JSON en .NET

Entonces para manejar JSON especialmente dentro de nuestras aplicaciones .NET, nada mejor que el gran framework, Json.NET creado por el talentoso James Newton-King. Quien lo ha dispuesto de manera free aún para el uso comercial. Y desde mi modo de ver, es la mejor librería para trabajar con JSON con .NET. Y además viendo que ya .NET es multiplataforma, entonces sería la mejor librería para trabajar JSON sobre cualquier plataforma. Te puedes bajar la dll a la vieja usanza o sencillamente incluir el paquete desde Nuget con el wizard o desde la consola NPM.

Creando modelos para nuestras APIs JSON con C#

Digamos eso sí, que lo anterior fue lo más obvio de este post. Pero bueno, ya teniendo como manipular JSON desde nuestro C#, lo siguiente que puede ocurrir entonces es que quisiéramos conectarnos a un API que nos pide le enviemos un json con la siguiente estructura:

 {
  "name": "FabrikamTravel",
  "description": "Frabrikam travel app for Windows Phone",
  "capabilities": {
    "versioncontrol": {
      "sourceControlType": "Git"
    },
    "processTemplate": {
      "templateTypeId": "6b724908-ef14-45cf-84f8-768b5384da45"
    }
  }
}

Podríamos ponernos a construir las clases a mano y emplear un montón de tiempo en esto.

Pero mejor tomar el ejemplo del api que nos da el developer y pasarlo por esta tool online:

image

 

Como se aprecia, el modelo generado en C# es muy bueno. Nos ahorramos montones de tiempo y si no es exactamente lo que queremos, al menos tenemos una gran aproximación a lo que requerimos.

Luego ya con esas clases y la ayuda de JSON.NET, podemos hacer serializaciones que nos emiten automáticamente el JSON requerido.

Generando datos de prueba JSON de manera masiva

Algunas APIs pueden requerir que enviemos registros para ser insertados en una base de datos. Estos registros, deberían ir representados en JSON. Pero generalmente la edición de éstos  es mucho más sencilla por ejemplo en Excel, que poniéndose a escribir el JSON a mano. Mi recomendación entonces es seguir usando Excel para crear los datos de prueba y luego los grabamos en formato CSV. Cuando ya los tenemos así, podemos copiar y pegar el contenido de este archivo y ponerlo en esta otra tool online:

image

El resultado es un muy bien estructurado JSON que podremos agregar a nuestras pruebas al API con la aplicación que estemos construyendo.

Y hablando de pruebas:

Prueba de APIs propias y de terceros

Una vez creamos un API generalmente ésta quedará expuesta en nuestra máquina de desarrollo a través del localhost. Y para no tener que escribir una aplicación web por nuestra propia cuenta, tenemos varias opciones.

curl:

Es una herramienta de consola que proviene del mundo Unix y nos permite hacer llamados HTTP y recibir respuesta en la misma consola. Hay muchas formas de obtenerlo. Existe la versión stand alone para Windows y también se puede obtener dentro del paquete de Cygwin que es uno de los intentos más notables hasta ahora de traer el mundo de la consola Linux a Windows. Si han instalado Git para Windows, ésta instalación también instala una emulación de la consola Bash del mundo *nix, que incluye por supuesto curl. Pero la opción más interesante para mí sin embargo, es usarlo desde Bash en Windows, luego de que ya es posible tener un subsistema de Linux formal dentro de Windows, gracias a las herramientas para desarrollador que vienen para Windows 10. Así que el bash que se ejecuta no es emulado sino realmente el bash de Linux (con algunas limitantes):

Por ejemplo, con una línea de comando consulté un API que tengo desplegada en Azure que sencillamente te retorna la IP actual con la que te reconocen desde internet:

image

Claro está que si el término azul no es lo tuyo y te gustan las tools más elaboradas, podrías usar el muy amigable PostMan que comenzó siendo una extensión de Chrome y ahora ya tiene su instalador standalone para Windows y otros sistemas operativos:

image

Aquí hago un llamado a la misma API anterior. Se pueden armar llamados HTTP de cualquier tipo y hay muchas ayudas visuales para crear el cuerpo de los mensajes y para formatear las respuestas desde el server de manera que sean fácilmente entendibles por el developer.

Pero definitivamente la navaja suiza para trabajar con APIs es Fiddler. Su interfaz para nada tan amigable con el usuario tal vez nos haga sentir como si estuviéramos frente a los controles de un Boeing 747. Pero por ejemplo a diferencia de PostMan, Fiddler permite rastrear todo el trafico web desde y hacia nuestra máquina de desarrollo. Nos permite simular certificados https, correr scripts de automatización avanzados y muchos más. Puedes leer más de fiddler en este blog post que escribí hace años.

Visualizando JSON entendiblemente

Puede que luego de probar alguna API recibamos un montón de JSON que queramos ver de manera estructurada, sabiendo la cantidad de nodos que hay en cada nivel y demás. Para eso, nada mejor que esta gran tool online:

image4

Generación de esquemas JSON

Sí, hay esquemas JSON. Así como habían esquemas XSD, también hay documentos que pueden describir un JSON. Y esto es muy útil para poder desarrollar otras herramientas que manejen JSON o para poder validar la estructura de un documento JSON en general. La herramienta que les mostraré a continuación, permite que le pasemos un ejemplo de un documento JSON y en vez de generarnos por ejemplo clases C#, lo que nos genera es el dichoso esquema que obviamente viene escrito en JSON. Plataformas como Logic Apps en Azure por ejemplo, requieren que especifiquemos un esquema JSON para los datos de entrada de las aplicaciones y qué mejor que contar con una herramienta online como ésta:

image

En conclusión este es el pequeño arsenal de tools con el que me defiendo cuando trabajo bien sea creando o consumiendo APIs. Si tienes otras tools para recomendar, bienvenidas en los comentarios!

Comments