RAML: a language for the API documentation

RAML: a language for the API documentation

These days I’m in love with RAML, a programming language created to document effectively the API.

In fact, I am participating all’APIConUK, a three-day conference focused on the world of API. Among the many interesting talks (the days are very intense: five each day), one in particular caught my attention … and the case would have it, the one dedicated to RAML was just the first.

With RAML you can not only document your APIs, but also use some tools written in JavaScript and NodeJS and also released in OpenSource modes, that allow the user to access to the API documentation and test interactive realtime operation without having to go through tools as a generic REST Console, or even CURL.

The API editor for the producer and the console and the notebook dedicated to the consumer of the API can be used without installing anything on your servers, taking advantage of a public installation made ​​available by MuleSoft.

The syntax of Raml is very similar to YAML, so it is really easy and intuitive to write your own API documentation and the documentation on the official website is also really complete and intuitive.
We will start with header:

#%RAML 0.8
---
title: e-BookMobile API
baseUri: http://api.e-bookmobile.com/{version}
version: v1
Then go on to list the resources that meet their API with any internal resources. For example:
 /users:
/authors:
  /{authorname}:
/books:

Then we switch to list the methods used in each resource, such as always using the indentation on YAML:

/books:
   get:
   put:
   post:
   /{bookTitle}:
     get:
     put:
     delete:
     /author:
       get:
     /publisher:
       get:

We are almost at the end; fit the parameters to be passed to each method:

 /books:
   /{bookTitle}
     get:
       queryParameters:
         author:
         publicationYear:
         rating:
         isbn:
     put:
       queryParameters:
         access_token:

and complete them with the attributes for each parameter:

/books:
   /{bookTitle}
     get:
       queryParameters:
         author:
           displayName: Author
           type: string
           description: An author's full name
           example: Mary Roach
           required: false
         publicationYear:
           displayName: Pub Year
           type: number
           description: The year released for the first time in the US
           example: 1984
           required: false
         rating:
           displayName: Rating
           type: number
           description: Average rating (1-5) submitted by users
           example: 3.14
           required: false
         isbn:
           displayName: ISBN
           type: string
           minLength: 10
           example: 0321736079?
      put:
        queryParameters:
          access_token:
            displayName: Access Token
            type: string
            description: Token giving you permission to make call
            required: true

Finally, now that we have described in detail the calls, do the same with the answers:

/books:
   /{bookTitle}:
     get:
       description: Retrieve a specific book title
       responses:
         200:
           body:
             application/json:
              example: |
                 {
                   "data": {
                     "id": "SbBGk",
                     "title": "Stiff: The Curious Lives of Human Cadavers",
                     "description": null,
                     "datetime": 1341533193,
                     "genre": "science",
                     "author": "Mary Roach",
                     "link": "http://e-bookmobile.com/books/Stiff",
                   },
                   "success": true,
                   "status": 200
                 }

At this point the file with the API documentation is ready and there is nothing left to do but make it available to our users through the tools that we have mentioned earlier.

Leave a Reply

Your email address will not be published. Required fields are marked *

ten − six =