API Documentation with RAML

Last Update: 17.11.2017. By Jens in APIs | API Business

This is the third part of the API documentation series. In the last part we explored the first solution using API Blueprint a bit, and in this article, we are covering RAML.

RAML

RAML is an acronym for RESTful API Modeling Language. It is a language like API Blueprint to describe APIs, in case of RAML explicitly for RESTful API. Nonetheless, you can use it for any web API close to that. It is also a type 1 of our classifications made in the overview - you write the docs separate.

Contrary to API Blueprint it uses YAML as a base format. YAML (YAML Ain’t Markup Language) is a language for describing data serialization in a human-readable way. However, humans tend here to be developers.

YAML is spoken by many developers, and thus they can pick up RAML easier. It supports many practices of reusing like in regular programming and makes it easy to create your documentation from small building blocks.

It has also been around for some time now and thus has a healthy ecosystem around the base spec. The tools range from parsing the spec to rendering documentation in various formats to test tools checking your API against the documentation.

Our previous example would look like:

#%RAML 1.0
---
title: Book Metadata API
baseUri: http://book-metadata-api.example.com/{version}
version: v1
description: |
  I am a long description text.

  With multiple **paragraphs**.

documentation:
 - title: Home
   content: |
     Welcome block. Content can be in a separate file.

types:
   book:
     mediaType: application/json
     properties:
      isbn:
          description: "ISBN"
          type: "string"
      title:
          description: "title"
          type: "string"

/books:  
  get:
    description: Retrieves all **books**
    responses:
      200:
        body:
          application/json:
            type: book[]  
            example: | 
              [
               {
                 "isbn": "9781111",
                 "title": "How to ..."
               }
              ]

Using raml2html as a docs generator, we will get a documention like:

It provides an overview with regular text and a list of all the endpoints. It does also create a detail view of each endpoint which is accessible via a popup.

Advantages

A huge benefit is that it is also based on a widespread technology. Many developers work with YAML and will have no problem writing docs in RAML when they picked up the language essentials.

It also defines, again, the structure of your documentation and guides you building a useful API documentation.

A healthy ecosystem exists, and there are plenty of tools for designing, writing, test support and generating the final documentation.

Disadvantages

It is meant for RESTful APIs, so if your web API deviates too much from these principles, you might not be able to properly make use of it. Like API Blueprint, it does not fit when you work with non-HTTP APIs.

Another disadvantage is that it is mainly a language built for developers. YAML is a data serialization format /language and thus was created by developers for developers. So, if you don’t use a design tool for building the API or documentation, your non-tech staff might have a hard time picking it up and be productive with it. In the worst case, your devs will have to write and maintain the full documentation.

Conclusion

It is a mature tech and does the job fine. However, it is apparently built for technical staff, and this might not be the right choice in your context. I’ve made the experience that it is already hard enough to get non-techs to use anything other than Word…

Besides that, it has a healthy ecosystem, and you get the docs done with it.

In the next part, we will take a look at OpenAPI aka Swagger.

Update Januar 2018

I used RAML recently during the Kanban API Series and ran into several problems. The issues were all related to the Major Spec change of RAMl form v0.8 to v1.0. The Spec itself worked as did the api-designer editor I used. However, the testing tools which allow black box testing of your API did not work with RAML v1.0. Even several Month/Years later, they still only support RAML v0.8. Be aware that other tools might be unusable with the newer RAML version.