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 (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.[5]

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:[6]

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.[10][11] SmartBear 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:

API gateways supporting RAML

Furthermore you can convert your RAML specification to either OpenAPI or API Blueprint using APIMATIC, thus enabling you to use further API gateways.

See also

Alternative RESTful Modeling Languages

Notes

  1. ↑ Not registered with IANA

References

  1. ↑ "Announcing RAML 1.0 GA | RAML Blog". Retrieved 11 August 2016.
  2. ↑ "RAML 1.0". Retrieved 26 May 2017.
  3. ↑ "RAML — RESTful API Modeling Language". Retrieved 15 July 2014.
  4. ↑ "RAML Workgroup".
  5. ↑ "RAML - Trademark Details". 26 May 2017.
  6. ↑ "Why RAML is More than Another Proprietary Specification". 11 April 2014.
  7. ↑ "API Design Tooling From RAML". 3 March 2014.
  8. ↑ "Anypoint for APIs: An Interview with Uri Sarid". 25 February 2014.
  9. ↑ "An Example of API Design using RAML". 11 April 2014.
  10. ↑ "SmartBear, Linux Foundation launch Open API Initiative to Evolve Swagger". ProgrammableWeb. 2015-11-10. Retrieved 2016-04-21.
  11. ↑ "New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services". www.linuxfoundation.org. Retrieved 2016-04-22.
  12. ↑ Montcheuil, Yves de. "In 2016, the need for an API meta-language will crystallize". InfoWorld. Retrieved 2016-04-25.
  13. ↑ "Amazon API Gateway Now Supports Swagger Definition Import". InfoQ. Retrieved 2016-04-25.
This article is issued from Wikipedia. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.