RAML: THE RESTFUL API MODELING LANGUAGE (PART 7)

Request Data:

Let’s revisit our “Create an album” endpoint, which you’ll recall involves making a POST request to the/albums URI.

We can expand upon this by describing the data someone is required to include, the mechanism used to provide it, and some specifics about the various fields.

Here’s an example:

/albums:
 get:
  description: Retrieve a list of albums
 post:
  description: Create a new album
 body:
  application/x-www-form-urlencoded:
   formParameters:
    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}$
     required: true
    name:
     description: The name of the album
     type: string
     required: true
    artist:
     description: The name of the artist
     type: string
     required: true
    label:
     description: The label it was released under
     type: string
     required: false
    year:
     description: The year the album was released
     type: integer
     required: false
     minimum: 1900
     maximum: 3000

Here we’re defining the expected request body when POSTing to this endpoint. We’re indicating that the request should be of type application/x-www-form-urlencoded.

Next, we break down the expected request body into parameters with the formParameters property. Then we list the possible fields, provide some meta-data about each one, as well as the expected type. We can also indicate which fields are required and which are optional, as well as some validation rules – in this case we use a regular expression to dictate the format of the ISRC, and some relatively sensible boundaries for the year of release.