RAML Workgroup Ships Version 1.0 of the RESTful API Modeling Language

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.

Screenshot -- RAML 1.0's Data Typing In Action: Modeling data is a very common task when designing APIs. Whether it has to do with retrieving data from or writing data to a resource, data models help developers to understand the type of data they are dealing with. Traditionally, the approach to data modeling within the context of API description has involved JSON or XML, neither of which is perfectly-suited to the task. To solve that problem RAML 1.0 introduces a new system that creates models with a strongly typed language. The example above shows different types as well as type nesting: Both Artist and Song are defined as objects and the Artist object is referenced inside the Song object as well. Both are also represented as arrays too.

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.

Screenshot -- RAML 1.0's Multiple Example Support: One of the main principles of great API design is to give developers all the information they need to consume any of the resources an API makes available to them. This makes it easier to get started developing applications with the API and its associated service(s). In other words, faster time to "Hello World." Developers like to see examples that fully express the different possibilities for what can be retrieved from or provided to an API. The example above shows how RAML 1.0 not only facilitates the documentation of examples within the API's description; it shows how the specification can offer multiple examples. In this case, one example contains the song's description while the other one doesn't. Both examples show different values for the "is_band" field, thereby also indirectly conveying its boolean nature. With RAML 1.0, an API Designer can define multiple examples, expressing the different possibilities and make it easier for developers to consume their APIs.

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.

Be sure to read the next API Design article: MuleSoft Releases API Workbench IDE for Modern API Design

About the Author:

ProgrammableWeb Staff If you have a press release that you would like to contribute to ProgrammableWeb, you are encouraged to send it to editor@programmableweb.com for consideration.

Promoted