RESTful API Modeling Language (RAML) is a

YAML YAML ( and ) (''see '') is a human-readable data-serialization language. It is commonly used for configuration files and in applications where data is being stored or transmitted. YAML targets many of the same communications applications as Exte ...

-based language for describing static

API An application programming interface (API) is a way for two or more computer programs to communicate with each other. It is a type of software Interface (computing), interface, offering a service to other pieces of software. A document or standa ...

s (but not REST APIs). It provides all the information necessary to describe APIs on the level 2 of the

Richardson Maturity Model The Richardson Maturity Model (RMM) is a maturity model suggested in 2008 by Leonard Richardson which classifies Web APIs based on their adherence and conformity to each of the model's four levels. The aim of the research of the model as stated b ...

. Although designed with RESTful APIs in mind, RAML is not capable of describing APIs that 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 API Web Science, Kin Lane, SOA Software, and Cisco. Development is managed by the RAML Workgroup. The current workgroup signatories include technology leaders from

MuleSoft MuleSoft, LLC. is a software company headquartered in San Francisco, California, that provides integration software for connecting applications, data and devices. Started in 2006, the company's Anypoint Platform of integration products is designe ...

(Uri Sarid, CTO),

AngularJS AngularJS is a discontinued free and open-source JavaScript-based web framework for developing single-page applications. It was maintained mainly by Google and a community of individuals and corporations. It aimed to simplify both the development ...

(Misko Hevery, Project Founder),

Intuit Intuit Inc. is an American business software company that specializes in financial software. The company is headquartered in Mountain View, California, and the CEO is Sasan Goodarzi. Intuit's products include the tax preparation application Tu ...

(Ivan Lazarov, Chief Enterprise Architect),

Airware Airware (incorporated as Unmanned Innovation, Inc.) was an American venture-funded startup that provided commercial unmanned aerial vehicles for enterprises. The company ceased operations on September 14, 2018. Airware was founded in 2011 in New ...

(Peter Rexer, Director of Product - Developer Platform), Programmable Web and API Science (John Musser, Founder),

SOA Software Akana is a provider of computer software products for application programming interface (API) management. The company was founded as Digital Evolution and was later known as SOA Software. In November 2016, Akana was acquired by Rogue Wave Softwar ...

(Tony Gullotta, Director of Development),

Cisco Cisco Systems, Inc., commonly known as Cisco, is an American-based multinational digital communications technology conglomerate corporation headquartered in San Jose, California. Cisco develops, manufactures, and sells networking hardware, ...

(Jaideep Subedar, Senior Manager, Product Management - Application Integration Solutions Group),

VMware VMware, Inc. is an American cloud computing and virtualization technology company with headquarters in Palo Alto, California. VMware was the first commercially successful company to virtualize the x86 architecture. VMware's desktop software ru ...

(Kevin Duffey, Senior MTS Engineer),

Akamai Technologies Akamai Technologies, Inc. is an American content delivery networkJ. Dilley, B. Maggs, J. Parikh, H. Prokop, R. Sitaraman, and B. Weihl. (CDN), cybersecurity, and cloud service company, providing web and Internet security services. Akamai's Inte ...

(Rob Daigneau, Director of Architecture for Akamai's OPEN API Platform) and Restlet (Jerome Louvel, CTO and Founder). 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 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: * 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 (now

OpenAPI Specification The OpenAPI Specification, previously known as the Swagger Specification, is a specification for a machine-readable interface definition language for describing, producing, consuming and visualizing RESTful web services. Previously part of the S ...

), 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 The Linux Foundation (LF) is a non-profit technology consortium founded in 2000 as a merger between Open Source Development Labs and the Free Standards Group to standardize Linux, support its growth, and promote its commercial adoption. Additi ...

, called the Open API Initiative was set up in 2015 to standardize the description of HTTP APIs. A number of companies including SmartBear,

Google Google LLC () is an American multinational technology company focusing on search engine technology, online advertising, cloud computing, computer software, quantum computing, e-commerce, artificial intelligence, and consumer electronics. ...

, IBM and

Microsoft Microsoft Corporation is an American multinational technology corporation producing computer software, consumer electronics, personal computers, and related services headquartered at the Microsoft Redmond campus located in Redmond, Washing ...

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: 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: * line 7, 12: defines traits, invoked in multiple places * line 12: an Include file * line 13, 14: define a "resource" data type "/songs"; uses previously defined traits * line 15, 19, 37: defines

HTTP The Hypertext Transfer Protocol (HTTP) is an application layer protocol in the Internet protocol suite model for distributed, collaborative, hypermedia information systems. HTTP is the foundation of data communication for the World Wide Web, ...

methods * line 25, 36:

MIME types A media type (also known as a MIME type) is a two-part identifier for file formats and format contents transmitted on the Internet. The Internet Assigned Numbers Authority (IANA) is the official authority for the standardization and publication o ...

API gateways supporting RAML

Apigee Apigee Corp. was an API management and predictive analytics software provider before its merger into Google Cloud. It was founded in 2004 as Sonoa Systems before being rebranded as Apigee in 2010. Apigee was acquired by Google in a deal worth ...

AWS API Gateway Amazon Web Services, Inc. (AWS) is a subsidiary of Amazon that provides on-demand cloud computing platforms and APIs to individuals, companies, and governments, on a metered pay-as-you-go basis. These cloud computing web services provide di ...

by AWS (throug
AWS API Gateway Importer
*

Akana Akana is a provider of computer software products for application programming interface (API) management. The company was founded as Digital Evolution and was later known as SOA Software. In November 2016, Akana was acquired by Rogue Wave Softwar ...

* Restlet Furthermore, you can convert your RAML specification to either OpenAPI or

API Blueprint An application programming interface (API) is a way for two or more computer programs to communicate with each other. It is a type of software interface, offering a service to other pieces of software. A document or standard that describes how t ...

usin
APIMATIC
thus enabling you to use further API gateways.

Alternative HTTP API Modeling Languages

API Blueprint
* WADL

Notes

References

{{Reflist

External links

RAML official website

RAML Repositories on Github

RAML Open Specification and Tools Released to Aid in API Design

MuleSoft founder Ross Mason on avoiding API armageddon

Spring WebService to RAML maven plugin
Application programming interfaces Markup languages