RAML: THE RESTFUL API MODELING LANGUAGE (PART 3)

Resources:

the next step is to outline the available resources. Here’s an example:

/albums:
 displayName: Album
/artists:
 displayName: Artist

Here we’ve defined two top-level resources, (musical) albums and resources. What we haven’t yet done is described the HTTP methods which can be used to interact with them, but first let’s drill down a little and look at resource URIs and sub-resources.

Let’s suppose specific albums are represented by their ISRC (International Standard Recording Code); so let’s expand our /albums resource to describe this:

/albums:
 /{isrc}:
  uriParameters: 
      isrc:
        description: The International Standard Recording Code which uniquely identifies this album
  type: string
  pattern: ^[a-zA-Z]{2}\-[0-9a-zA-Z]{3}\-\d{2}\-\d{5}$

As you can see, URI parameters are denoted by curly brackets. The uriParameters property can be used to provide additional information about these parameters, both meta-information (in this case, adescription) as well as a concrete definition of their format – in this example, the data type and a regular expression which defines the specific format.

Using nesting, we can describe sub-resources. For example, suppose we provide an endpoint to retrieve an individual album’s tracklisting:

/albums:
 /{isrc}:
  uriParameters: 
      isrc:
        description: The International Standard Recording Code which uniquely identifies this album
  type: string
  pattern: ^[a-zA-Z]{2}\-[0-9a-zA-Z]{3}\-\d{2}\-\d{5}$
  /tracks:
   displayName: Tracklisting

You can have as much nesting of resources as you wish; just use YAML-style indentation.