Seite wählen

Designing your next API with RAML and the API Workbench

von | 1. Januar 1970 | Allgemein, Software Engineering

Alain Lompo

Alain Lompo

Ehemaliger Senior Developer bei Senacor

Introducing RAML

RAML stands for RESTful API Modeling Language: it is a

human- and machine-readable language for the definition of a RESTful application programming interface (API)

RAML is a REST-oriented documentation languages that uses YAML formating (instead of JSON or other formats). RAML uses a top-down specification approach, therefore it breaks down the system into its various sub-components of which it describes and explains the behaviour.

RAML vs swagger

Swagger is probably the most popular framework for describing an API using a common language understandable by everyone and RAML may not be able to change that soon, however RAML has it’s own unique place in the API description and documentation frameworks ecosystem. RAML’s design makes it able to support REST API documentation as well as APIs that don’t strictly adhere to REST standards (for example those that are using other design architecture like SOAP).

Comparing language support
Language Supported by swagger? Supported by RAML?
Java yes yes
Javascript yes yes
Node.js yes yes
.Net languages yes yes
Go yes yes
Haskell yes yes
Php yes yes
Python yes yes
Ruby yes yes
Scala yes yes
Is the API war over?

On April 20th 2017, Mulesoft, the creator of RAML announced that they were joining the OpenAPI Initiative created by Smartbear and based on Swagger. Does it mean that the API war is over? Let’s see…RAML is still out there and it is still advocated as The simplest way to design API on its official website, and also looking for a better option than just war is not necessarily a full blown act of capitulation. Be as it may RAML is still out there and harnessing it’s potential is still a very valuable experience. It’s internal design and capabilities may inspire someone to produce the next leading API framework.

Basic usage of RAML

Before starting to properly design our API with RAML, we need to input a few required metadatas such as:

  • the title
  • the baseUri
  • the protocols
  • the mediaType

These metadatas are important as they provide the ability to track back the API (via the title and baseUri) and also to set the expectancy in terms of type of datas from the API developer or the API documentation reviewer’s perspective.

Now let’s go through the basic steps to design an API with RAML. We will create a weather API, but first let’s set up our IDE.

Installing the Api workbench

The API Workbench is installable as an Atom package. So first install Atom if you do not have it already. Then launch the console command: apm install api-workbench.

The other option would be to go through the Packages menu: select Settings View ==> Install Packages/Themes. Then type api-workbench in the input field and click on the Packages button. It should display the api workbench package: click on the associated Install button, and the package will be installed.

Creating the basic structure of a RAML Api

The simplest way to create the basic structure of a RAML Api is by using the helpers provided by the Api Workbench instead of writing a single line of code. Let’s do that now. Assuming that you are designing your next Awesome meeting service Api. Start by creating a meeting-api.raml file with Atom.

Next, from inside the file area use the contextual menu Add new...==> Create new API


In the next step one can enter a few meta datas for the API such as it’s name, it’s version and its root URI. One should also keep the following two checkboxes checked for obvious reasons

  • Create sample resource
  • Generate 1.0 model


As the result the API Workbench generate the basic API structure for us without us ever writing one line of code: how cool that is!!!


An even easier way

What we did in a few steps to create the basic API structure we can do in even lesser steps by using the Packages> Api Workbench> Create RAML Project menu item.


Next we can define the metadatas and other important parameters for our API project via a new dialog:


With this one step, we obtain the equivalent of the former structure + a project folder structuration:


Inserting resources and methods

The API-Workbench IDE is context sensitive. For example when we are editing a raml file, the available tools are different depending on which line we are, that is the tools panels are adapted to offer us the best possible help.

For example by positioning ourselves at the Title line level, the details panel will look like the following:


However by moving away from this line one would notice the changes. Let’s position ourselves at the root of our API design file, the Details panel should normally show the Add new resource button. Click on it to display the Resource adding dialog.

From now on let’s stick to building the coolest weather API ever. Therefore let’s add a cities resources and for now using only a GET and a POST Http verbs


Adding method bodies and responses

We have generated a /cities resource with two empty methods for GET and POST. Now we need to fill them with informations related to the outgoing and incoming datas

Let’s once again take advantage of the context sensitive tooling of the API-Workbench. By positioning the cursor at the get method we can see that the Details panel ‚adapts itself‘ to the new context. By simply clicking on the responses button we can add a default response template with 200 response code.

Now let’s add a response body. For that we focus on the 200: add click on the body button: a default body template fo type application/json is added to our get method.

Let’s apply a similar approach to generate a body for our post method. At this step your /cities resource should look like the following:


And that’s a pretty good basic API structure for a starter!

Dealing with sub-resources

Now let’s take advantage of sub-resources to allow addition and delition of resources. Let’s position on the /cities resources and click on the Add new resource button in the Details panel and let’s add a /{id} resource with put and delete methods.

Now let’s add a body to the put method and a response to the delete method using the same approach as we did above. Use the http code 204 as the response code for delete since we do not send any content with it.

At this step our /cities resource and sub resource should look like:

Inserting examples and types

So far we have only described what type of application media we are using. Let describe now the content of our JSON.

Starting with our post method, and using the Intellisense capacities of the API Workbench, let’s position ourselves right after the post: declaration and press Enter. Next try to type the „t“ character, it will suggest the whole type key: accept it by typing Enter and API Workbench will insert the whole type code template for you.

Defining resource type
Extracting resource types
Adding resource types parameters
Defining method parameters and traits
Reusing artefacts
Reusing traits and resource types
Extracting and reusing libraries