RAML (software)

{{Short description|YAML-based language for describing RESTful APIs}}

{{Infobox file format

| name = RAML

| mime = application/raml+yamlNot registered with IANA

| extension = .raml

| extended from = YAML

| latest_release_version = 1.0

| latest_release_date = {{Start date|2016|05|16}}{{cite web |url=http://blog.raml.org/announcing-raml-10-ga/ |title=Announcing RAML 1.0 GA {{pipe}} RAML Blog |access-date=11 August 2016}}

| owner = RAML Workgroup

| standard = {{URL|https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/}}

| url = {{URL|https://raml.org/}}

}}

RESTful API Modeling Language (RAML) is a YAML-based language for describing static APIs (but not REST APIs).{{cite web |url=https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/|title=RAML 100.o |website=GitHub |access-date=26 May 2017}} 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.{{cite web |url=http://raml.org/ |title=RAML — RESTful API Modeling Language |access-date=15 July 2014}}

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.{{Cite web|url=https://dzone.com/articles/raml-or-openapi-how-about-both|title=RAML or OpenAPI - How About Both? - DZone Integration|website=dzone.com|language=en|access-date=2017-10-04}} Development is managed by the RAML Workgroup.{{cite web|title=RAML Workgroup|url=http://raml.org/about/workgroup}} 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.{{cite web |url=https://trademarks.justia.com/861/37/raml-86137689.html |title=RAML - Trademark Details |date=26 May 2017}}

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. {{Citation needed span|text=There are plans to move towards more strictly RESTful APIs as the evolution of technology and the market permits.|date=January 2023}}

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:{{cite web |url=http://www.infoq.com/articles/eventlog-api-raml/ |title=Why RAML is More than Another Proprietary Specification |date=11 April 2014}}

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{{cite web |url=http://apievangelist.com/2014/03/01/api-design-tooling-from-raml/ |title=API Design Tooling From RAML |date=3 March 2014}}
MuleSoft originally started using Swagger (now OpenAPI Specification), 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{{cite web |url=http://www.infoq.com/news/2014/02/anypoint-api-sarid |title=Anypoint for APIs: An Interview with Uri Sarid |date=25 February 2014}}
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{{cite web |url=http://www.infoq.com/articles/eventlog-api-raml/ |title=An Example of API Design using RAML |date=11 April 2014}}

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.{{Cite news|url=http://www.programmableweb.com/news/%E2%80%8Bsmartbear-linux-foundation-launch-open-api-initiative-to-evolve-swagger/2015/11/10|title=SmartBear, Linux Foundation launch Open API Initiative to Evolve Swagger|date=2015-11-10|work=ProgrammableWeb|access-date=2016-04-21|archive-date=2016-11-09|archive-url=https://web.archive.org/web/20161109214454/http://www.programmableweb.com/news/%E2%80%8Bsmartbear-linux-foundation-launch-open-api-initiative-to-evolve-swagger/2015/11/10|url-status=dead}}{{Cite web|url=http://www.linuxfoundation.org/news-media/announcements/2015/11/new-collaborative-project-extend-swagger-specification-building|title=New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services|website=www.linuxfoundation.org|access-date=2016-04-22|url-status=dead|archive-url=https://web.archive.org/web/20160427104213/http://www.linuxfoundation.org/news-media/announcements/2015/11/new-collaborative-project-extend-swagger-specification-building|archive-date=2016-04-27}} SmartBear donated the Swagger specification to the new group. RAML and API Blueprint are also under consideration by the group.{{Cite web|url=http://www.infoworld.com/article/3014506/apis/in-2016-the-need-for-an-api-meta-language-will-crystallize.html|title=In 2016, the need for an API meta-language will crystallize|last=Montcheuil|first=Yves de|website=InfoWorld|date=14 December 2015 |access-date=2016-04-25}}{{Cite web|url=http://www.infoq.com/news/2016/04/Amazon-API-Gateway-Swagger|title=Amazon API Gateway Now Supports Swagger Definition Import|website=InfoQ|access-date=2016-04-25}}

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}

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:

/{songId}:

get:

responses:

200:

body:

application/json:

schema: |

{ "$schema": "http://json-schema.org/schema",

"type": "object",

"description": "A canonical song",

"properties": {

"title": { "type": "string" },

"artist": { "type": "string" }

"required": [ "title", "artist" ]

}

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 methods
line 25, 36: MIME types.

API gateways supporting RAML

Apigee
MuleSoft
AWS API Gateway by AWS (through [https://github.com/awslabs/aws-apigateway-importer AWS API Gateway Importer])
Akana
Restlet

Furthermore, you can convert your RAML specification to either OpenAPI or API Blueprint using [https://apimatic.io/transformer APIMATIC], thus enabling you to use further API gateways.

Alternative HTTP API Modeling Languages

OpenAPI Specification
[http://apiblueprint.org/ API Blueprint]
WADL

Notes

References

External links

[http://raml.org/index.html RAML official website]
[https://github.com/search?o=desc&q=raml&ref=cmdform&s=updated&type=Repositories RAML Repositories on Github]
[http://olensmar.blogspot.ca/2013/12/a-raml-apihub-plugin-for-soapui.html A RAML/APIHub Plugin for SoapUI]
[http://blog.programmableweb.com/2013/10/23/raml-open-specification-and-tools-released-to-aid-in-api-design/ RAML Open Specification and Tools Released to Aid in API Design] {{Webarchive|url=https://web.archive.org/web/20140321032847/http://blog.programmableweb.com/2013/10/23/raml-open-specification-and-tools-released-to-aid-in-api-design/ |date=2014-03-21 }}
[http://diginomica.com/2014/04/11/mulesoft-founder-avoiding-api-armageddon/#.VA-LZGSwKUQ MuleSoft founder Ross Mason on avoiding API armageddon]
[http://www.itbusinessedge.com/blogs/it-unmasked/mulesoft-makes-api-management-more-accessible.html MuleSoft Makes API Management More Accessible]
[https://github.com/oleg-cherednik/maven-raml-plugin Spring WebService to RAML maven plugin]

Category:Application programming interfaces

Category:Markup languages