RAML (software)

RAML
Filename extension	`.raml`
Internet media type	`application/raml+yaml^{[n 1]}`
Developed by	RAML Workgroup
Latest release	1.0 (May 16, 2016 (2016-05-16)^[1])
Extended from	YAML
Standard	raml.org/raml-10-spec
Website	raml.org

RESTful API Modeling Language (RAML) is a YAML-based language for describing RESTful APIs.^[2] 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 (hence the description "practically-RESTful"). It encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices.^[3]

History

RAML was first proposed in 2013. The initial RAML specification was authored by Uri Sarid, Emiliano Lesende, Santiago Vacas, and Damian Martinez. Development is managed by the RAML Workgroup.^[4] The current workgroup signatories include technology leaders from MuleSoft Inc. (Uri Sarid), AngularJS (Misko Hevery, Project Founder), Intuit Inc. (Ivan Lazarov, Chief Enterprise Architect), Box Inc. (Peter Rexer, Senior Platform Product Manager), PayPal Inc. (Jason Harmon, Head of API Design), Programmable Web & API Web Science (John Musser, Founder), Kin Lane (Presidential Innovation Fellow, Department of Veteran Affairs), SOA Software (Tony Gullotta, Director of Technology), and Cisco (Samar Choudary, Lead Architect, Application Integration Service Group). RAML is a trademark of CR7^[5]

The current version of RAML is not restricted to strictly RESTful APIs because it would have not applied to almost any existing APIs and not been feasible for most API initiatives to adopt today, so RAML is starting with the basics of RESTful APIs—resources, methods, parameters, and bodies that need not be hypermedia with plans to evolve from there

While RAML could end up being just a proprietary vendor language there are a number of reasons why this language is interesting to the broader API community:^[6]

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^[7]
Mulesoft originally started with 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^[8]
API descriptions are often verbose and repetitive which can hinder their structure, understanding and consumption. RAML has introduced language features that support structured files and inheritance that address cross-cutting concerns^[9]

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 variety of companies, including Swagger, Google, IBM and Microsoft are founding members.^[10]^[11] Swagger donated the Swagger specification to the new group. RAML and API Blueprint are also under consideration by the group.^[12]^[13]

Example

This is an example RAML file. As with YAML, indentation shows nesting.

 1   #%RAML 0.8
 2 
 3   title: World Music API
 4   baseUri: http://example.api.com/{version}
 5   version: v1
 6   traits:
 7     - paged:
 8         queryParameters:
 9           pages:
10             description: The number of pages to return
11             type: number
12     - secured: !include http://raml-example.com/secured.yml
13   /songs
14     is: [ paged, secured ]
15     get:
16       queryParameters:
17         genre:
18           description: filter the songs by genre
19     post:
20     /{songId}:
21       get:
22         responses:
23           200:
24             body:
25               application/json:
26                 schema: |
27                   { "$schema": "http://json-schema.org/schema",
28                     "type": "object",
29                     "description": "A canonical song",
30                     "properties": {
31                       "title":  { "type": "string" },
32                       "artist": { "type": "string" }
33                     },
34                     "required": [ "title", "artist" ]
35                   }
36               application/xml:
37       delete:
38         description: |
39           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

Alternative RESTful Modeling Languages

Notes

↑ Not registered with IANA

References

↑ "Announcing RAML 1.0 GA | RAML Blog". Retrieved 11 August 2016.
↑ "RAML 0.8". Retrieved 15 July 2014.
↑ "RAML — RESTful API Modeling Language". Retrieved 15 July 2014.
↑ "RAML Workgroup".
↑ "RAML Branding Policy".
↑ "Why RAML is More than Another Proprietary Specification". 11 April 2014.
↑ "API Design Tooling From RAML". 3 March 2014.
↑ "Anypoint for APIs: An Interview with Uri Sarid". 25 February 2014.
↑ "An Example of API Design using RAML". 11 April 2014.
↑ "SmartBear, Linux Foundation launch Open API Initiative to Evolve Swagger". ProgrammableWeb. 2015-11-10. Retrieved 2016-04-21.
↑ "New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services". www.linuxfoundation.org. Retrieved 2016-04-22.
↑ Montcheuil, Yves de. "In 2016, the need for an API meta-language will crystallize". InfoWorld. Retrieved 2016-04-25.
↑ "Amazon API Gateway Now Supports Swagger Definition Import". InfoQ. Retrieved 2016-04-25.

External links

This article is issued from Wikipedia - version of the 11/26/2016. The text is available under the Creative Commons Attribution/Share Alike but additional terms may apply for the media files.