El lenguaje de modelado de API RESTful ( RAML ) es un lenguaje basado en YAML para describir API RESTful . [2] Proporciona toda la información necesaria para describir las API RESTful o prácticamente RESTful. Aunque está diseñado con las API RESTful en mente, RAML es capaz de describir las API que no obedecen a todas las restricciones de 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 basado en el mérito. [3]
Extensión de nombre de archivo | .raml |
---|---|
Tipo de medio de Internet | aplicación / raml + yaml [n 1] |
Desarrollado por | Grupo de trabajo RAML |
Último lanzamiento | |
Extendido desde | YAML |
Estándar | github |
Sitio web | raml |
Historia
RAML se propuso por primera vez en 2013. La especificación RAML inicial fue creada por Uri Sarid, Emiliano Lesende, Santiago Vacas y Damian Martinez, y 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. [4] El desarrollo lo gestiona el grupo de trabajo RAML. [5] Los signatarios del grupo de trabajo actual incluyen líderes tecnológicos de MuleSoft (Uri Sarid, CTO), AngularJS (Misko Hevery, Fundador del proyecto), Intuit (Ivan Lazarov, Arquitecto jefe de empresa), Airware (Peter Rexer, Director de Producto - Plataforma de desarrollo) , Ciencia de API y Web programable (John Musser, Fundador), Software SOA (Tony Gullotta, Director de Desarrollo), Cisco (Jaideep 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) y Restlet (Jerome Louvel, director de tecnología y fundador). RAML es una marca comercial de MuleSoft. [6]
Muy pocas API 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 API 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.
Hay varias razones por las que RAML ha dejado de ser un lenguaje de proveedor propietario y ha demostrado ser interesante para la comunidad de API en general: [7]
- RAML ha sido de código abierto junto con herramientas y analizadores para lenguajes comunes. El desarrollo de RAML será 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 [8].
- 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 [9]
- Las descripciones de las API suelen ser detalladas y repetitivas, lo que puede dificultar su comprensión y uso y hacer que la adopción de las API sea más lenta. RAML ha introducido características de lenguaje que admiten archivos estructurados y herencia que abordan preocupaciones transversales [10]
Una nueva organización, bajo el patrocinio de la Fundación Linux , llamada Open API 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. [11] [12] SmartBear donó la especificación Swagger al nuevo grupo. El grupo también está considerando RAML y API Blueprint. [13] [14]
Ejemplo
Este es un archivo RAML de ejemplo. Al igual que con YAML, la sangría muestra anidamiento.
#% RAML 0.8 título : API de World Music baseUri : http://example.api.com/{version} versión : v1 rasgos : - paginado : queryParameters : páginas : descripción : el número de páginas para devolver tipo : número - asegurado : ! Incluir http://raml-example.com/secured.yml / canciones : es : [ paginado , protegido ] obtener : queryParameters : genero : descripción : filtra las canciones por género publicación : / {songId} : obtener : respuestas : 200 : cuerpo : aplicación / json : esquema : | {"$ esquema": "http://json-schema.org/schema", "tipo": "objeto", "description": "Una canción canónica", "propiedades": { "título": {"tipo": "cadena"}, "artist": {"type": "string"} }, "obligatorio": ["título", "artista"] } aplicación / xml : borrar : descripción : | Este método * eliminará * una ** canción individual **
Algunos aspectos destacados:
- línea 7, 12: define rasgos, invocados en múltiples lugares
- línea 12: un archivo de inclusión
- línea 13, 14: defina un "recurso" tipo de datos "/ canciones"; usa rasgos previamente definidos
- línea 15, 19, 37: define métodos HTTP
- línea 25, 36: tipos MIME .
Puertas de enlace API que admiten RAML
Además, puede convertir su especificación RAML a OpenAPI o API Blueprint utilizando APIMATIC , lo que le permite utilizar más puertas de enlace API.
Ver también
- Especificación de OpenAPI
- Descripción general de los lenguajes de descripción de API RESTful, incluida la especificación OpenAPI, RAML, WADL, WSDL y otros.
- MuleSoft
- Transferencia de estado representacional
- YAML
- API de Java para servicios web RESTful
- SoapUI
- SOAtest
- Reducción
Lenguajes alternativos de modelado RESTful
- Especificación de OpenAPI
- Plano de API
- WADL
Notas
- ^ No registrado en IANA
Referencias
- ^ "Anuncio de RAML 1.0 GA | Blog de RAML" . Consultado el 11 de agosto de 2016 .
- ^ "RAML 1.0" . Consultado el 26 de mayo de 2017 .
- ^ "RAML - Lenguaje de modelado de API RESTful" . Consultado el 15 de julio de 2014 .
- ^ "RAML o OpenAPI - ¿Qué tal ambos? - Integración DZone" . dzone.com . Consultado el 4 de octubre de 2017 .
- ^ "Grupo de trabajo RAML" .
- ^ "RAML - Detalles de la marca comercial" . 26 de mayo de 2017.
- ^ "Por qué RAML es más que otra especificación patentada" . 11 de abril de 2014.
- ^ "Herramientas de diseño de API de RAML" . 3 de marzo de 2014.
- ^ "Anypoint para API: una entrevista con Uri Sarid" . 25 de febrero de 2014.
- ^ "Un ejemplo de diseño de API usando RAML" . 11 de abril de 2014.
- ^ "SmartBear, la Fundación Linux lanza la iniciativa de API abierta para evolucionar Swagger" . Web programable . 2015-11-10 . Consultado el 21 de abril de 2016 .
- ^ "Nuevo proyecto colaborativo para ampliar la especificación Swagger para la construcción de aplicaciones y servicios conectados" . www.linuxfoundation.org . Archivado desde el original el 27 de abril de 2016 . Consultado el 22 de abril de 2016 .
- ^ Montcheuil, Yves de. En 2016, cristalizará la necesidad de un metalenguaje API ” . InfoWorld . Consultado el 25 de abril de 2016 .
- ^ "Amazon API Gateway ahora admite la importación de definiciones Swagger" . InfoQ . Consultado el 25 de abril de 2016 .
enlaces externos
- Sitio web oficial RAML
- Repositorios RAML en Github
- Un complemento RAML / APIHub para SoapUI
- Especificación abierta RAML y herramientas lanzadas para ayudar en el diseño de API
- Ross Mason, fundador de MuleSoft, sobre cómo evitar el armagedón de las API
- MuleSoft hace que la gestión de API sea más accesible
- Complemento Spring WebService a RAML maven