This article may rely excessively on sources too closely associated with the subject , potentially preventing the article from being verifiable and neutral.(April 2016) |
Filename extension | .raml |
---|---|
Internet media type | application/raml+yaml [n 1] |
Developed by | RAML Workgroup |
Latest release | |
Extended from | YAML |
Standard | github |
Website | raml |
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]
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]
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:
Furthermore, you can convert your RAML specification to either OpenAPI or API Blueprint using APIMATIC, thus enabling you to use further API gateways.
The Resource Description Framework (RDF) is a method to describe and exchange graph data. It was originally designed as a data model for metadata by the World Wide Web Consortium (W3C). It provides a variety of syntax notations and data serialization formats, of which the most widely used is Turtle.
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 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:
JSON is an open standard file format and data interchange format that uses human-readable text to store and transmit data objects consisting of name–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.
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 Languages (WSDL), which can also be used to describe REST web services.
Data exchange is the process of taking data structured under a source schema and transforming it into a target schema, so that the target data is an accurate representation of the source data. Data exchange allows data to be shared between different computer programs.
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.
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.
An application programming interface (API) is a connection between computers or between computer programs. It is a type of software interface, offering a service to other pieces of software. A document or standard that describes how to build 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.
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. Originally developed to support the Swagger framework, it became a separate project in 2015, overseen by the OpenAPI Initiative, an open-source collaboration project of the Linux Foundation.
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 high-performance web framework for building HTTP-based service APIs in Python 3.8+. It uses Pydantic and type hints to validate, serialize and deserialize data. FastAPI also automatically generates OpenAPI documentation for APIs built with it. It was first released in 2018.