Improving our project setup flow with RAML

profile picture

Mario Web Developer

4 Aug 2016  ·  4 min read

Everybody knows that time is money, and you can never have enough of either! Well, that might be a cliché, but we still made it one of our main goals at November Five to not waste any time.

As a part of this endeavour, we are always working to improve the development flow by making it faster and more efficient.

One of the key things to work on is the way we start a project. We want to make sure there are no obstacles in the way so that everyone can kick off swiftly. As frontend developers, the biggest impediment we all encounter at this stage is not having an environment to start working in, with a running server and working APIs. Manually mocking a server isn’t usually an option, because at the very beginning, we don’t even know what the server will look like.

This is the point where we turned to our friends in Team Backend and discovered an amazing tool: RAML.

What is RAML?

RAML (RESTful API Modeling Language) is a YAML-based language that helps define a RESTful server. Because it’s very simple and readable, it allows us to easily design, mock, test and document APIs.

How does that work exactly, you ask? Let’s say we have to create a TODO app. We want to avoid wasting time, and even if the backend development hasn’t started yet, we have a basic idea of what the server setup should look like:

#%RAML 1.0
title: Our awesome TODO app
version: v1

    description: Return the list of TODOs
            schema: !include schemas/todos.json
            example: !include examples/todos.json

    description: Create a TODO
        schema: !include schemas/post-todo.json
        example: !include examples/post-todo.json
        body: !!null

This defines what the first two calls should look like. Once we’ve written this up, we send it to the backend developers for review. This improves communications and makes us an active part in backend development, giving us the ability to foresee future changes by the backend team early on, and prepare our code for those changes.

But at this point, we aren’t ready to code… yet.

The next step: mocking up

A lot of tools come together with RAML: two of them are Osprey and Osprey Mock Service. Osprey is an npm package that takes a RAML file as input and generates a validation proxy with an existing server. Based on Osprey, the Mock Service generates a functional server that uses the examples in the RAML specs as responses.

So if we use Osprey Mock Service on our RAML specifications,

osprey-mock-service -f todo-specs.raml -p 8080

we’ll have a working RESTful server on the address If we now try to make a request, Osprey will validate it against the json schema and Mock Service will return the json example, both included in the RAML file.

Also, Osprey comes not only as an executable, but also as an ExpressJS middleware, which means that we can easily write a small NodeJS script and add some business logic to our mocked server.

This way, we’ve created a middle layer that is always up to date with the back-end’s progress, and we can really get started.


Another cool tool that we really like to use, next to RAML, is Abao. Abao is another npm package that creates some automated testing by reading a RAML file.

It’s very simple: it goes through each request that the RAML file accepts and checks that the responses are also compliant to the docs. It also allows us to define some hooks that can make some small changes to a single test case (e.g. if we want to test a validation error response, we’ll deliberately add an error to the request).

It is very useful to check if the APIs are respecting the docs and to avoid regressions. Also, since it’s possible to run Abao against any environment, we can check, for instance, if the production server is working as expected in no more than a couple of seconds.

How it improved our flow

Since we started using RAML in our flow, it’s become much easier and faster to start each web project. Now the backend team can start at the same time as the frontend team and when things are ready, we can just merge the two just by changing the API’s endpoint.

Discussing the API’s structure also noticeably improved our internal communication and refined our knowledge about the principles of REST. Also, the documentation-first approach, together with the awesome tools that come with RAML helps us take care of our documentation’s cleanliness and order.