La mayoría de los proyectos en los que participamos en mi trabajo requieren diseñar e implementar APIs de acceso para las aplicaciones móviles y webapps. Este diseño requiere definir un sistema de autenticación (por ejemplo uno basado en tokens como puede ser JWT) y cada uno de los endpoints que serán accesibles. En esta definición de endpoints debemos decidir que campos de entrada y de salida tendrá cada uno.

Para diseñar una buena API se requiere emplear los verbos HTTP adecuadamente utilizando RESTFul, pero también debemos de implementar un diseño intuitivo, una buena documentación y que ésta represente fielmente a la implementación. A parte de que la implementación sea buena, es muy importante que la documentación asociada a ella sea completa y esté actualizada al 100% teniendo controlado el comportamiento esperado por cada request. En mi opinión, mantener este compromiso suele ser bastante complicado pero utilizando las herramientas adecuadas se puede simplificar y beneficiar al equipo de desarrollo, y a los futuros desarrolladores que se puedan encargar del desarrollo software.

Desde hace unos meses hacia aquí hemos decidido utilizar RAML para documentar y diseñar nuestras apis, aunque estuvimos planteando otras soluciones como Swagger. Vamos a conocer en detalle que es y para que sirve este lenguaje.

¿Que es RAML y por qué usarlo en nuestras APIs?

RAML es el acrónimo de “Restful Api Modeling Language” y se trata de un lenguaje de modelado para definir apis REST con una sintaxis bastante sencilla y fácilmente comprensibles tanto para seres humanos como para sistemas  software. Este lenguaje permite definir recursos, métodos, parámetros, respuestas, tipos de medios y otros componentes HTTP básicos. Básicamente es una especificación no propietaria y totalmente independiente basada en YAML y JSON. En otras palabras, lo que nos permite es escribir la especificación de las apis siguiendo un estándar.

La gran ventaja de implementar API con RAML es que te centras totalmente en el “contrato” que ofrece el endpoint; esto permite comenzar generando la documentación, para la cual  una vez esté lista, existen distintos generadores que nos generan el “scaffolding” básico del servicio e incluso servicios que nos devuelvan respuestas simuladas para arrancar con nuestro testing.

Esta metodología favorece el proceso de testing aportándonos el entorno perfecto para usar TDD. Básicamente, definimos la api, escribimos tests para consumir esa api y empezamos a construir la implementación real y necesaria para validar tanto los tests como la especificación descrita.

¿Como escribir RAML?

Puedes escribirlo tan solo con un fichero normal con la extensión .raml y procesarlo con distintas herramientas. Personalmente usamos una herramienta oficial de Mulesoft llamada Api Designer (https://github.com/mulesoft/api-designer). Esta herramienta es un editor construido con angularjs y que puedes instalar a través de NPM en tu ordenador.

También os comparto un video oficial de la comunidad Mulesoft en la que realiza un ejemplo de un fichero raml utilizando api designer.

Ejemplo de diseño en RAML

Algunas herramientas útiles

• Raml JS Parser: https://github.com/raml-org/raml-js-parser
• Raml Java parser: https://github.com/raml-org/raml-java-parser
• SOAPUI Raml Plugin: https://github.com/SmartBear/soapui-raml-plugin

Para finalizar este post, os recomiendo realizar el tutorial oficial para empezar a crear vuestros ficheros RAM.