Design and document your RESTful API using RAML

Creating documentation is one of the more tedious aspects of the software development process. Not that writing algorithms and object-oriented class hierarchies isn’t tedious, but it often seems (at least to me) that writing plain text explaining your code is more tedious than writing the code itself. Also, if you consider yourself an Agile practitioner (as I do), you’re always evaluating the time spent vs. value added whenever you write much about working software outside of and separate from the working software you already wrote.

I find myself constantly analyzing and re-analyzing the darn thing. Is it too long? Too short? Too wordy? Oversimplified? Too granular? Too vague? Should I have even attempted this?

I don’t claim this conundrum is unique to me. It’s one of the main reasons that many software projects are undocumented or under-documented. Because of this, a tool that helps you write clear, simple documentation, and saves you time doing it, is an invaluable find.

RAML is one of these fabulous creatures.

I was introduced to RAML by a colleague while working on an ASP.NET Web API project over the the last few months. What I like best about RAML is that it solves multiple documentation problems through the creation and maintenance of a single file:

• You can design and modify your API collaboratively without writing / re-writing any code.
• The syntax is simple and to-the-point, reducing time needed to properly describe the routes, actions and parameters.
• This document serves as a team “contract” of sorts throughout the development process. Server-side developers, client-side / mobile developers, and testers – everyone – can see and agree on the intended behavior and content of your API requests and responses.
• When the project is done, you’re left with an excellent artifact to hand off and / or publish describing exactly how your API works.

Now that’s what I call valuable documentation. To get started, all you really need to write a RAML doc is a text editor and access to the spec. However the team over at MuleSoft has developed a superb browser-based editor for RAML, complete with spec references and “intellisense” of sorts. Best of all – it’s free to use. They’ve labeled it as “API Designer” on their site; here’s a sample (click the image for a better view):

I used it for the project I mentioned above; I found it to be far quicker than writing a text-only version. Being able to click on and view the routes on the right side of the screen was also a really handy feature during various design and testing discussions. I found the API Designer to be a solid tool, and highly recommend it.

So the next time you kick off a REST API project, *start* with the documentation – and write some RAML.