# RAML (lenguaje)

RESTful API Modeling Language (RAML) es un lenguaje de modelado para definir APIs RESTful con una sintaxis sencilla y fácilmente comprensible tanto para los seres humanos como para sistemas software. Básicamente es una especificación no propietaria y totalmente independiente basada en YAML y JSON, es decir, permite escribir la especificación de las APIs siguiendo un estándar. Proporciona toda la información necesaria para describir las API RESTful o prácticamente RESTful. Aunque está diseñado teniendo en cuenta las API RESTful, RAML es capaz de describir las API que no obedecen a todas las restricciones del REST (de ahí la descripción "prácticamente RESTful"). Fomenta la reutilización, permite el descubrimiento y el intercambio de patrones y tiene como objetivo el surgimiento de mejores prácticas basadas en el mérito.
La gran ventaja de implementar API con RAML es poder centrarse 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 crearán el "scaffolding" o esqueleto básico del servicio, e incluso servicios que devuelvan respuestas simuladas para empezar con las pruebas. Esta metodología favorece el proceso de testing aportando el entorno perfecto para usar TDD (Desarrollo guiado por pruebas). Básicamente, se define la API, se estiman tests para consumir esa API y se empieza a construir la implementación real y necesaria para validar tanto los test como la especificación descrita.

## Historia

La especificación RAML se propuso por primera vez en 2013 por Uri Sarid, Emiliano Lesende, Santiago Vacas y Damian Martinez. Además, obtuvo el apoyo de líderes tecnológicos como MuleSoft, AngularJS, Intuit, Box, PayPal, Programmable Web y API Web Science, Kin Lane, SOA Software y Cisco. El desarrollo fue gestionado por el grupo de trabajo RAML.
Los firmantes del grupo de trabajo actual incluyen los siguientes líderes tecnológicos:
* MuleSoft (Uri Sarid, CTO)
* AngularJS (Misko Hevery, Fundador del proyecto)
* Intuit (Ivan Lazarov, Arquitecto jefe de la empresa)
* Airware (Peter Rexer, Director de Producto - Plataforma de desarrollo)
* Programmable Web and API Science (John Musser, Fundador)
* SOA Software (Tony Gullotta, director de desarrollo)
* CISCO (Jaiddep Subedar, Senior Manager, Product Management - Application Integration Solutions Group)
* VMware (Kevin Duffey, Senior MTS Engineer)
* Akamai Technologies (Rob Daigneau, Director de arquitectura de la plataforma OPEN API de Akamai)
* Restlet (Jerome Louvel, director de tecnología y fundador)
RAML es una marca comercial de MuleSoft.
Muy pocas APIs existentes cumplen los criterios precisos para ser clasificadas como API RESTful. En consecuencia, como la mayoría de las iniciativas de API en la década de 2010, RAML se ha centrado inicialmente en los conceptos básicos de la APIs prácticamente RESTful, incluidos recursos, métodos, parámetros y cuerpos de respuesta que no necesitan ser hipermedia. Hay planes para avanzar hacia API RESTful más estrictas a medida que la evolución de la tecnología y el mercado lo permitan.
En estos puntos se verá por qué RAML es interesante para la comunidad de API:
* RAML es de código abierto junto con herramientas y analizadores para lenguajes comunes. El desarrollo de RAML está supervisado por un comité directivo de profesionales de API y UX, y existe un ecosistema emergente de herramientas de terceros que se están desarrollando en torno a RAML.
* MuleSoft originalmente comenzó a usar Swagger (ahora especificación OpenAPI), pero decidió que era más adecuado para documentar una API existente, no para diseñar una API desde cero. RAML evolucionó a partir de la necesidad de admitir el diseño de API por adelantado en un lenguaje sucinto y centrado en el ser humano.
* Las descripciones de las APIs suelen ser detalladas y repetitivas, lo que puede dificultar su comprensión y uso, y hacer que la adopción de la API sea más lenta. RAML ha introducido características de lenguaje que admiten archivos estructurados y herencia que abordan preocupaciones transversales.
Una nueva organización, bajo el patrocinio de la Fundación Linux, llamada OpenAPI Initiative se estableció en 2015 para estandarizar la descripción de las API RESTful. Varias empresas, incluidas SmartBear, Google, IBM y Microsoft, fueron miembros fundadores. SmartBear donó la especificación Swagger al nuevo grupo. El grupo también está considerado RAML y API Blueprint.

## Código de ejemplo

RAML permite el desarrollo rápido de una API utilizando una sintaxis accesible que puede escalar desde un pequeño proyecto hasta una aplicación empresarial.
Partes del código a destacar:
* Líneas 2-4: Nombre de la API, especificación de versión y URL base.
* Líneas 9-11: Especificación de los tipos de reutilizables para evitar duplicaciones y redundancias
* Líneas 13-22: Modelación de los endpoints con información de acceso, métodos de HTTP y parámetros.
* Líneas 29-32: Modelación de los múltiples tipos de respuesta, incluidos JSON y XML, dentro de una sola interfaz.

## Puertas de enlace API que admiten RAML

* Apigee
* MuleSoft
* AWS API Gateway de AWS
* Akana
Además, puede convertir su especificación RAML a OpenAPI o API Blueprint utilizando APIMATIC, lo que permite utilizar más puertas de enlace API.