RAML (software)

Last updated
RAML
Filename extension
.raml
Internet media type
application/raml+yaml [n 1]
Developed byRAML Workgroup
Latest release
1.0
May 16, 2016 (2016-05-16) [1]
Extended from YAML
Standard github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/
Website raml.org

RESTful API Modeling Language (RAML) is a YAML-based language for describing static APIs (but not REST APIs). [2] 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. [3]

Contents

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. [4] Development is managed by the RAML Workgroup. [5] 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. [6]

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 plans to move towards more strictly RESTful APIs as the evolution of technology and the market permits.[ citation needed ]

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

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. [11] [12] SmartBear donated the Swagger specification to the new group. RAML and API Blueprint are also under consideration by the group. [13] [14]

Example

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

#%RAML 0.8title:World Music APIbaseUri:http://example.api.com/{version}version:v1traits:-paged:queryParameters:pages:description:The number of pages to returntype:number-secured:!includehttp://raml-example.com/secured.yml/songs:is:[paged,secured]get:queryParameters:genre:description:filter the songs by genrepost:/{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:

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 HTTP API Modeling Languages

Notes

  1. ↑ Not registered with IANA

Related Research Articles

The Resource Description Framework (RDF) is a World Wide Web Consortium (W3C) standard originally designed as a data model for metadata. It has come to be used as a general method for description and exchange of graph data. RDF provides a variety of syntax notations and data serialization formats, with Turtle currently being the most widely used notation.

<span class="mw-page-title-main">Interface description language</span> Computer language used to describe a software components interface

An interface description language or interface definition language (IDL) is a generic term for a language that lets a program or object written in one language communicate with another program written in an unknown language. IDLs are usually used to describe data types and interfaces in a language-independent way, for example, between those written in C++ and those written in Java.

YAML(see § History and name) 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 Extensible Markup Language (XML) but has a minimal syntax that intentionally differs from Standard Generalized Markup Language (SGML). It uses Python-style indentation to indicate nesting and does not require quotes around most string values.

REST is a software architectural style that was created to guide the design and development of the architecture for the World Wide Web. REST defines a set of constraints for how the architecture of a distributed, Internet-scale hypermedia system, such as the Web, should behave. The REST architectural style emphasises uniform interfaces, independent deployment of components, the scalability of interactions between them, and creating a layered architecture to promote caching to reduce user-perceived latency, enforce security, and encapsulate legacy systems.

In computing, Web-Based Enterprise Management (WBEM) comprises a set of systems-management technologies developed to unify the management of distributed computing environments. The WBEM initiative, initially sponsored in 1996 by BMC Software, Cisco Systems, Compaq Computer, Intel, and Microsoft, is now widely adopted. WBEM is based on Internet standards and Distributed Management Task Force (DMTF) open standards:

<span class="mw-page-title-main">JSON</span> Open standard file format and data interchange

JSON is an open standard file format and data interchange format that uses human-readable text to store and transmit data objects consisting of attribute–value pairs and arrays. It is a commonly used data format with diverse uses in electronic data interchange, including that of web applications with servers.

<span class="mw-page-title-main">Web API</span> HTTP-based application programming interface used in web development

A web API is an application programming interface (API) for either a web server or a web browser. As a web development concept, it can be related to a web application's client side. A server-side web API consists of one or more publicly exposed endpoints to a defined request–response message system, typically expressed in JSON or XML by means of an HTTP-based web server. A server API (SAPI) is not considered a server-side web API, unless it is publicly accessible by a remote web application.

The Common Information Model (CIM) is an open standard that defines how managed elements in an IT environment are represented as a common set of objects and relationships between them.

The Web Application Description Language (WADL) is a machine-readable XML description of HTTP-based web services. WADL models the resources provided by a service and the relationships between them. WADL is intended to simplify the reuse of web services that are based on the existing HTTP architecture of the Web. It is platform and language independent and aims to promote reuse of applications beyond the basic use in a web browser. WADL was submitted to the World Wide Web Consortium by Sun Microsystems on 31 August 2009, but the consortium has no current plans to standardize it. WADL is the REST equivalent of SOAP's Web Services Description Language (WSDL), which can also be used to describe REST web services.

The Open Packaging Conventions (OPC) is a container-file technology initially created by Microsoft to store a combination of XML and non-XML files that together form a single entity such as an Open XML Paper Specification (OpenXPS) document. OPC-based file formats combine the advantages of leaving the independent file entities embedded in the document intact and resulting in much smaller files compared to normal use of XML.

Jakarta RESTful Web Services, is a Jakarta EE API specification that provides support in creating web services according to the Representational State Transfer (REST) architectural pattern. JAX-RS uses annotations, introduced in Java SE 5, to simplify the development and deployment of web service clients and endpoints.

<span class="mw-page-title-main">Web Services Description Language</span> XML-based interface description language

The Web Services Description Language is an XML-based interface description language that is used for describing the functionality offered by a web service. The acronym is also used for any specific WSDL description of a web service, which provides a machine-readable description of how the service can be called, what parameters it expects, and what data structures it returns. Therefore, its purpose is roughly similar to that of a type signature in a programming language.

This is a comparison of data serialization formats, various ways to convert complex objects to sequences of bits. It does not include markup languages used exclusively as document file formats.

In computing, Open Data Protocol (OData) is an open protocol that allows the creation and consumption of queryable and interoperable Web service APIs in a standard way. Microsoft initiated OData in 2007. Versions 1.0, 2.0, and 3.0 are released under the Microsoft Open Specification Promise. Version 4.0 was standardized at OASIS, with a release in March 2014. In April 2015 OASIS submitted OData v4 and OData JSON Format v4 to ISO/IEC JTC 1 for approval as an international standard. In December 2016, ISO/IEC published OData 4.0 Core as ISO/IEC 20802-1:2016 and the OData JSON Format as ISO/IEC 20802-2:2016.

<span class="mw-page-title-main">API</span> Software interface between computer programs

An application programming interface (API) is a way for two or more computer programs or components 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 to build or use such a connection or interface is called an API specification. A computer system that meets this standard is said to implement or expose an API. The term API may refer either to the specification or to the implementation. Whereas a system's user interface dictates how its end-users interact with the system in question, its API dictates how to write code that takes advantage of that system's capabilities.

The Sensor Observation Service (SOS) is a web service to query real-time sensor data and sensor data time series and is part of the Sensor Web. The offered sensor data consists of data directly from the sensors, which are encoded in the Sensor Model Language (SensorML), and the measured values in the Observations and Measurements encoding format. The web service as well as both file formats are open standards and specifications of the same name defined by the Open Geospatial Consortium (OGC).

Topology and Orchestration Specification for Cloud Applications (TOSCA), is an OASIS standard language to describe a topology of cloud based web services, their components, relationships, and the processes that manage them. The TOSCA standard includes specifications of a file archive format called CSAR.

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 web services. Previously part of the Swagger framework, it became a separate project in 2015, overseen by the OpenAPI Initiative, an open-source collaboration project of the Linux Foundation.

<span class="mw-page-title-main">Swagger (software)</span> Computing language

Swagger is a suite of tools for API developers from SmartBear Software and a former specification upon which the OpenAPI Specification is based.

FastAPI is a modern web framework for building RESTful APIs in Python. It is relatively fast and used for building APIs with Python 3.8+ based on standard Python-type hints. It was first released in 2018 and has since quickly gained popularity among developers due to its ease of use, speed and robustness.

References

  1. ↑ "Announcing RAML 1.0 GA | RAML Blog" . Retrieved 11 August 2016.
  2. ↑ "RAML 100.o". GitHub . Retrieved 26 May 2017.
  3. ↑ "RAML — RESTful API Modeling Language" . Retrieved 15 July 2014.
  4. ↑ "RAML or OpenAPI - How About Both? - DZone Integration". dzone.com. Retrieved 2017-10-04.
  5. ↑ "RAML Workgroup".
  6. ↑ "RAML - Trademark Details". 26 May 2017.
  7. ↑ "Why RAML is More than Another Proprietary Specification". 11 April 2014.
  8. ↑ "API Design Tooling From RAML". 3 March 2014.
  9. ↑ "Anypoint for APIs: An Interview with Uri Sarid". 25 February 2014.
  10. ↑ "An Example of API Design using RAML". 11 April 2014.
  11. ↑ "SmartBear, Linux Foundation launch Open API Initiative to Evolve Swagger". ProgrammableWeb. 2015-11-10. Archived from the original on 2016-11-09. Retrieved 2016-04-21.
  12. ↑ "New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services". www.linuxfoundation.org. Archived from the original on 2016-04-27. Retrieved 2016-04-22.
  13. ↑ Montcheuil, Yves de (14 December 2015). "In 2016, the need for an API meta-language will crystallize". InfoWorld. Retrieved 2016-04-25.
  14. ↑ "Amazon API Gateway Now Supports Swagger Definition Import". InfoQ. Retrieved 2016-04-25.
This page is based on this Wikipedia article
Text is available under the CC BY-SA 4.0 license; additional terms may apply.
Images, videos and audio are available under their respective licenses.