The RAML Workgroup has announced that the RAML 1.0 specification has been published along with a newly redesigned RAML.org website. RAML, otherwise known as RESTful API Modeling Language, is an API description language and specification whose objectives are to make it simple to collaboratively create, read, and reuse any or all elements of an API's design, thereby easing some of the burdens associated with API lifecycle management. RAML 1.0 includes new features and improvements such as new data-typing system, enhanced examples support, libraries, overlays and extensions, annotations, and more. The RAML Workgroup also announced the availability of API Workbench (beta), a new, freely available, full-featured IDE for "designing, building, testing, documenting and sharing RESTful HTTP APIs."
This article highlights some of the new features and improvements included in RAML 1.0. Visit the RAML.org website to read the complete list of what’s new.
Data-Typing System
As API description languages mature, one of their key roles as enablers of API design and easy consumability is to type the data that they work with. As such, data-types are a key feature in RAML 1.0, offering a streamlined way to replace lengthy schemas while providing easily human and machine-read information for API consumers and code generation platforms alike. Examples of these data types and their readability can be seen in the image below, a partial screenshot of a fictitious API design as it appears in API Workbench.
Enhanced Support for Examples
One of the most common developer complaints when it comes to working with APIs is the dearth of examples to help them to better understand the range of an API's possibilities. With RAML 1.0, every part of an API can be documented with multiple examples that are expressible in YAML (a human friendly data serialization standard). Examples are also annotatable so that semantics can be included. The next partial screenshot of the aforementioned API design as it appears in API Workbench, shows how examples can be incorporated directly into the API's design.
One of the key features of RAML 1.0 has to do with the readability of the syntax and the way examples can be provided for everything. At the time this article was published, it appeared that other description languages were not as robust on this front. Swagger, for example, makes allowances for examples. However, Swagger seems to be limited in the number of examples that can be offered.
In a fairly recent Swagger forum post on GitHub, the ability to allow for multiple response schemas for each response code is discussed. The forum post thread mentions that multiple example support in Swagger would violate the principles of determinism, a principle that Swagger currently adheres to. RAML 1.0, on the other hand, has found a way to provide as many examples as are needed so developers can gain a better understanding of an API's possibilities while also aiding the automatic generation of code, SDKs, and API documentation.
Here is a theoretical scenario to show the differences in how Swagger and RAML 1.0 handle examples.
