RAML: The RESTful API Modeling Language

Introduction

RAML (RESTful API Modeling Language) is a powerful tool for designing, documenting, and testing APIs. It provides a structured way to define APIs, making them more understandable and maintainable. In this post, we’ll explore the basics of RAML and dive into practical examples.

What Is RAML?

RAML is a vendor-neutral, open-specification language built on YAML 1.2 and JSON. Its primary purpose is to describe RESTful APIs. Think of it as the blueprint for your API—defining endpoints, methods, parameters, and data models.

Basic Syntax

Let’s start with a simple example. Imagine we’re building an API for a BookMobile—a digital library on wheels. Here’s a basic RAML definition:

#%RAML 1.0

title: BookMobile API

baseUri: http://api.bookmobile.com/{version}

version: v1

/songs:

get:

description: Get a list of songs based on the song title.

queryParameters:

songTitle:

description: "The title of the song to search (case insensitive)"

required: true

minLength: 3

type: string

responses:

200:

body:

application/json:

example: |

{

"songs": [

{

"songId": "550e8400-e29b-41d4-a716-446655440000",

"songTitle": "Get Lucky"

...

]

}

In this example:

We define the base URI (http://api.bookmobile.com/{version}) where our API lives.
The /songs resource has a GET method that accepts a songTitle query parameter.
The response contains a list of songs with their IDs and titles.

Resource Types and Traits

RAML allows us to create reusable components using resource types and traits. Let’s say we want to handle authentication consistently across our API. We can define a trait:

traits:

secured:

headers:

Authorization:

description: "Bearer token for authentication"

Now, we can apply this trait to specific resources:

/songs:

is: [secured]

...

Schemas and Validation

RAML also supports data validation using schemas. For instance, let’s define a schema for our song object:

schemas:

Song:

type: object

properties:

songId: string

songTitle: string

And use it in our response: