RESTful APIModeling Language is a YAML-based language for describing RESTful APIs. It provides all the information necessary to describe RESTful or practically RESTful APIs. Although designed with RESTful APIs in mind, RAML is capable of describing APIs that do not obey all constraints of REST. It encourages reuse, enables discovery and pattern-sharing and aims for merit-based emergence of best practices.
History
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 APIWeb Science, Kin Lane, SOA Software, and Cisco. Development is managed by the RAML Workgroup. The current workgroup signatories include technology leaders from MuleSoft, AngularJS, Intuit, Airware, Programmable Web and API Science, SOA Software, Cisco, VMware, Akamai Technologies and Restlet. RAML is a trademark of MuleSoft. 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 practically RESTful APIs including resources, methods, parameters, and response bodies that need not be hypermedia. There are plans to move towards more strictly RESTful APIs as the evolution of technology and the market permits. 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:
RAML has been open-sourced along with tools and parsers for common languages. The development of RAML will be overseen by a steering committee of API and UX practitioners, and there is an emerging ecosystem of third party tools being developed around RAML
MuleSoft originally started using Swagger, but decided it was best suited to documenting an existing API, not for designing an API from scratch. RAML evolved out of the need to support up-front API design in a succinct, human-centric language
API descriptions are often verbose and repetitive, which can make them difficult to understand and use, and slow adoption of the APIs. RAML has introduced language features that support structured files and inheritance that address cross-cutting concerns
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 RESTful APIs. A number of companies including SmartBear, Google, IBM and Microsoft were founding members. SmartBear donated the Swagger specification to the new group. RAML and API Blueprint are also under consideration by the group.
Example
This is an example RAML file. As with YAML, indentation shows nesting. #%RAML 0.8 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: 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:
line 7, 12: defines traits, invoked in multiple places
