RAML: THE RESTFUL API MODELING LANGUAGE (PART 2)

RAML File Structure:

A RAML file starts with a declaration, indicating the format:

#%RAML 0.8

Typically you’d then provide some meta-information about your API, for example:

title: My Example API
version: v1

You should then provide the Base URI for your API. At its simplest, it can be in the following format:
baseUri: http://api.acme.com/

You can also use URI parameters. For example it’s common practice to incorporate a version identifier into API URLs; if you’re taking that approach with yours, you can do this:
baseUri: http://api.acme.com/{version}/

We’ll look at URI parameters in more detail later on, since they become vital when describing resources. But should you need to, you can include additional parameters in your base URI. Amazon’s S3, for example, incorporates the name of the bucket you’re working with into the base URI.

You can also indicate whether your API is available over HTTPS by setting the protocols field, for example:
protocols: [ HTTP, HTTPS ]

You can specify the default media type which your API will return, for example:
mediaType: application/json

Later when we look at responses, we’ll look at how you can describe multiple response media types, and what to expect from them.

You can also incorporate additional documentation – or pages – into your RAML file. For example:
documentation
 - title: Home
  content: |
   This example documentation forms part of a tutorial for a 
   [Sitepoint](http://www.sitepoint.com/) article.

There are some other things you can include here, such as how security is implemented, as well as defining traits.