you are here

RAML – Efficient, Easy API Documentation

In case you missed the latest headlines, I am absolutely in LOVE with RAML. We’re talking about the “You and I” by One Direction kind of love. And yes, I listen to One Direction… don’t judge.

The reason for this new found infatuation of mine is actually pretty simple… API documentation is a PAIN. One of the challenges Constant Contact faced with their old API (before the relaunch in May 2013) was documentation getting out of sync, or having incorrect data. Then there was the issue of having documentation scattered across multiple pages with multiple examples- some correct, most after years of revisions- not.

As API’s have exploded from a whopping 4 open APIs in 2005 to over 13,000 today, the industry has been scrambling to solve documentation problems. On top of that, developers are increasingly demanding more and more tools to make development easier. One solution has been the emergence of multi-language SDKs- however this only adds to the mess as SDKs are also constantly being updated, and in many cases are backwards incompatible. Sure they prevent users from having to learn your API – but they have to learn a whole new program altogether to replace it with.

Enter RAML- an open source project based on YAML and JSON with the hopes of making documentation not only easy, but efficient. Rather than having thousands upon thousands of files and standards, RAML let’s you put all your API definitions in one place; a single, simple .raml file.

And writing a RAML script couldn’t be easier- you can download the open source API Designer that combines a RAML IDE with a live console preview, or use MuleSoft’s free Anypoint API Portal shown below (disclaimer, I work for MuleSoft):

The API Designer then generates a simple, light-weight RAML file, such as the one I created for my basic GitHub Repo API:

Now all of this by itself isn’t very impressive, I mean there are a ton of great IDE’s out there, and several JavaScript based editors. Where the magic comes in is with the different opensource RAML tools, including the freely available API Console (available on GitHub) that generates complete and interactive documentation that let’s your users not only review your endpoints, but test them out in real time!

Of course this is just the tip of the iceberg! There are a ton more RAML projects including a JavaScript API Notebook that lets you enable live testing and exploring of your API, and even let’s you save popular use cases as gists that can be versioned, forked, or shared! There’s also a plugin for the AnyPoint Studio IDE, Node.js plugins, a SoapUI plugin, a GULP plugin, and a RAML to HTML converter!

You can read the RAML spec, and view all RAML projects at RAML.org.

Disclaimer: I work for MuleSoft in their Dev Relations Department, and as such it’s my job to share these tools with the dev community. However, that doesn’t include my personal blog… I wrote this post because I really believe RAML will help solve the API documentation dilemma, and make our lives as devs easier… and I really can’t wait to see how this community grows, or how this project evolves!

Share this Page:
Facebook Twitter Linkedin Reddit Tumblr Email

Leave a Reply

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