Muchas veces desbordados por las necesidades (urgentes) exponemos componentes internos de nuestras aplicaciones en servicios REST públicos. La inercia nos ha llevado a ir creando este tipo de APIs sin un diseño previo. Lo que conlleva problemas por la falta de planificación, lo que se traduce en la inconsistencia entre los objetos y métodos, sin hablar de agujeros de seguridad.
Afortunadamente, la tendencia está cambiando. Cada vez toma más importancia el diseño previo de APIs utilizando herramientas que tengan en cuenta la usabilidad, la necesidades de los consumidores/aplicaciones que vayan utilizar los servicios, permitan realizar mocks testeables, posibilitar el versionado y, por supuesto, crear de forma conjunta al desarrollo de la documentación.
API Blueprint, RAML y Swagger representan tres excelentes herramientas para diseñar APIs. Podemos diseñar sobre el papel antes de su implementación la definición de la API en formato JSON o usando markdown para describir la interfaz, estructura y el modelo de datos.
API Blueprint
Con API Blueprint tenemos un amplio ecosistema entorno al desarrollo de APIs. Cubriendo el ciclo de vida completo nos encontramos con un lenguaje de markdown para escribir la definición y transformarla en JSON. Lo cual mejora la legibilidad, pensado para humano y no maquinas.
Podemos usar Node.JS, .NET o Ruby directamente para realizar el binding con nuestra API. También posibilita el uso de herrramientas con Apiary.io para crear documentación interactiva, crear API mocks, validaciones, etc… combinado con Dredd para realizar testig y CI. También cuenta con plugin para Sublime Text y Atom para escribir las especificaciones.
RAML
RAML es la definición de RESTful API Modeling Language, el cual permite describir servicios REST de forma completa. Destaca la capacidad de reutilización de componentes y patrones para aplicar en las definiciones como bestpractices. Está construido a partir de estándares como YAML y JSON.
Cada API está definida con la versión de RAML que está usando junto a una serie de características en su descripción: título, versión, base URI. RAML permite definir patrones usando traits, resourceTypes y SecuritySchemes minimizando la repetición en las definiciones. Podemos definir las respuestas y ejemplos escritos en la definición como documentación.
Swagger
Swagger parte también como una definición pero su potencia reside en el framework implementado en Scala, Java (también con Spring), Javascript, Ruby, PHP que permite sobre todo ir escribiendo al mismo tiempo que implementamos el código las definiciones del API en Swagger, así como una documentación interactiva y fácilmente mantenible. Todo lo que cambie en el código de la API se refleja automáticamente en la documentación junto a un sandbox.
Conclusión
Estas tres herramientas tienen un gran potencial para la creación y diseño de APIs. Sobre todo cuando, como comentábamos al principio, se quiere crear un diseño previo a la implementación. Además son un gran aliado para desacomplar la implementación dependiente de una API cuando se trabaja en paralelo pudiendo crear mocks y conjuntos de tests basados en su definición.
En Genbeta Dev | Los diferentes modelos de negocio de una API y sus desarrolladores, Swagger, framework para generar documentación de APIs RESTful y un sandbox para probar llamadas
