RAML: THE RESTFUL API MODELING LANGUAGE (PART 1)

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

Writing RAML

The first thing to note is that RAML is a derivative of YAML. You’ll find it easier to work with RAML if you’ve written YAML before, but if you haven’t then it’s relatively straightforward.

Because they’re simply text files, you can of course use any text editor or IDE to create and edit them. However, a better option is to use the Anypoint platform. It provides an API editor, which allows you to edit RAML files with auto-completion, validation as-you-type and an interactive preview of some generated, interactive documentation.

To use Anypoint, you’ll first need to sign up – which is free – then add an API, then click “Define an API in API Designer”.

If you’d rather use Sublime, there’s a plugin you can use. It’s available via Package Control; simply do a search for “RAML Syntax Highlighter”.