Blog

- April 12, 2017

We are happy to announce that Restlet Studio now supports RAML 1.0 export and import. Let’s take this opportunity to have a look at the differences between RAML 1.0 and its main counterpart, OAS 2.0.

What is RAML 1.0?

RAML (RESTful API Modeling Language) is one of the most popular API definition languages along with OAS 2.0 (formerly known as Swagger Specification 2.0), and is well-known within the industry. It allows for simple API modeling, yet provides advanced features like resource nesting, data type inheritance, modularization and reusability.

What sets it apart?

A general emphasis on structure and reuse

RAML 1.0 encourages high reuse of the different API building blocks, this goes hand in hand with a very structured approach, in its way to model resources, data types, as well as more abstract, high-level features such as resource types and traits.

Nested resources

Resources are a central element in API design. They are characterised by their path (the last part of the url), that uniquely identifies the resource.

While most definition languages define resources as a list, RAML 1.0 allows you to nest them in a tree structure, which enables reuse of shared elements like URI parameters.

Example of flat modelization

/user/{userId}/profile:
  uriParameters:
    userId: string

/user/{userId}/posts:
  uriParameters:
    userId: string

/user/{userId}/posts/{postId}:
  uriParameters:
    userId: string
    postId: string

Example of nested modelization

/user/{userId}:
  uriParameters:
    userId: string

  /profile:
  
  /posts:
    /{postId}:
      uriParameters:
        postId: string

A versatile type system with advanced features

RAML 1.0 comes with its own type language, inspired from object oriented programming, that can be used to describe all typed elements, be they URI parameters, headers, query parameters or bodies.

Like OAS 2.0, RAML 1.0 allows users to declare types and reuse them, however it also provides advanced features like type specialization via inheritance, union types, etc.
Those interested in learning the intricacies of RAML 1.0 types should head over to the specification.

A highly modular language that encourages reuse

Like OAS 2.0, RAML 1.0 allows users to extract parts of their API definitions to dedicated files in order to reuse them. However, along with the usual type reuse, RAML steps it up a notch by introducing the concepts of resource types, traits and overlays.

For example, a resource type can be viewed as a resource ‘skeleton’ (the resource equivalent of a supertype), on which you can declare HTTP methods, security requirements, etc. Resources can then derive from the resource type, inheriting its attributes without the need to redefine them.

In addition, all these reusable elements can be grouped together in RAML libraries.

This is a topic that was covered in a previous post, which provides a few examples. 

In a nutshell

As we have seen, from a technical point of view RAML 1.0 shows several noteworthy design choices that make it an attractive API definition language for power users, without sacrificing simplicity in its core features.

Of course, one should not dismiss the importance of other variables such as community and tooling, which were not the focus of this post. So let’s wrap up with some general pros and cons for RAML 1.0 and OAS 2.0.

 

 

Try Restlet Studio today

Restlet Studio allows API designers to craft APIs, and supports both RAML 1.0 and OAS 2.0 import and export. Give it a try to easily see how your own API looks in either language.