RAML, the RESTful API Modeling Language

In a recent article I introduced Slate, a static site generator specifically designed for writing API documentation. This time around, I’m going to look at something which in many ways is even better.

But first, if you’ll indulge me for just a moment, I’d like to begin by quoting myself from that article;

[an] API is only as good as its documentation

I think it’s worth repeating, since it’s all-too-frequently overlooked, and it’s one of the motivations for this short series of articles on some of the tools out there to help you write great documentation.

Slate is a useful tool, but despite the relatively rigid structure of the pages themselves, the actual documentation is pretty freeform.

RAML (RESTful API Modeling Language) provides a structured, unambiguous format for describing a RESTful API. It allows you to describe your API; the endpoints, the HTTP methods to be used for each one, any parameters and their format, what you can expect by way of a response and more.

You can use RAML in a number of ways;

• It can be used in the design and specification stage to describe the API you plan to build


• You can use RAML to generate documentation


• RAML can be used to implement interactive API consoles


• You can test against RAML


• It be used to generate mock API responses

In this article I’ll primarily look at generating documentation; in a later article I’ll look at how you can integrate RAML into your API testing. But first, let’s look at how to write a RAML document.

Continue reading %RAML, the RESTful API Modeling Language%

by Lukas White via SitePoint