| RAML | |
| Mime: | application/raml+yaml[1] |
| Extension: | .raml |
| Extended From: | YAML |
| Latest Release Version: | 1.0 |
| Latest Release Date: | [2] |
| Owner: | RAML Workgroup |
RESTful API Modeling Language (RAML) is a YAML-based language for describing static APIs (but not REST APIs).[3] It provides all the information necessary to describe APIs on the level 2 of the Richardson Maturity Model. Although designed with RESTful APIs in mind, RAML is not capable of describing APIs that obey all constraints of REST (it cannot describe an API obeying HATEOAS, in particular). It encourages reuse, enables discovery and pattern-sharing and aims for merit-based emergence of best practices.[4]
RAML was first proposed in 2013. The initial RAML specification was authored by Uri Sarid, Emiliano Lesende, Santiago Vacas and Damian Martinez, and garnered support from technology leaders like MuleSoft, AngularJS, Intuit, Box, PayPal, Programmable Web and API Web Science, Kin Lane, SOA Software, and Cisco.[5] Development is managed by the RAML Workgroup.[6] The current workgroup signatories include technology leaders from MuleSoft (Uri Sarid, CTO), AngularJS (Misko Hevery, Project Founder), Intuit (Ivan Lazarov, Chief Enterprise Architect), Airware (Peter Rexer, Director of Product - Developer Platform), Programmable Web and API Science (John Musser, Founder), SOA Software (Tony Gullotta, Director of Development), Cisco (Jaideep Subedar, Senior Manager, Product Management - Application Integration Solutions Group), VMware (Kevin Duffey, Senior MTS Engineer), Akamai Technologies (Rob Daigneau, Director of Architecture for Akamai's OPEN API Platform) and Restlet (Jerome Louvel, CTO and Founder). RAML is a trademark of MuleSoft.[7]
Very few existing APIs meet the precise criteria to be classified as RESTful APIs. Consequently, like most API initiatives in the 2010s, RAML has initially focussed on the basics of APIs including resources, methods, parameters, and response bodies that need not be hypermedia.
There are a number of reasons why RAML has broken out from being a proprietary vendor language and has proven interesting to the broader API community:[8]
A new organization, under the sponsorship of the Linux Foundation, called the Open API Initiative was set up in 2015 to standardize the description of HTTP APIs. A number of companies including SmartBear, Google, IBM and Microsoft were founding members.[12] [13] SmartBear donated the Swagger specification to the new group. RAML and API Blueprint are also under consideration by the group.[14] [15]
This is an example RAML file. As with YAML, indentation shows nesting.
title: World Music API baseUri: http://example.api.com/ version: v1 traits: - paged: queryParameters: pages: description: The number of pages to return type: number - secured: !include http://raml-example.com/secured.yml /songs: is: [paged, secured ] get: queryParameters: genre: description: filter the songs by genre post: /: get: responses: 200: body: application/json: schema: | application/xml: delete: description: | This method will *delete* an **individual song**
Some highlights:
Furthermore, you can convert your RAML specification to either OpenAPI or API Blueprint using APIMATIC, thus enabling you to use further API gateways.