RAML: THE RESTFUL API MODELING LANGUAGE (PART 5)

Describing Responses:

We need to be able to describe the responses a user can expect.

In order to describe responses, we need to drill down a few more levels. First, we need to describe the possible response codes, and thereafter we need to break down responses into their components – typically, the response body – and then the possible response media types. Here’s an example to make that a little clearer:

/albums:
 /{isrc}:  
  get:
   description: Retrieve the specified album
  responses:
       200:
         body:
           application/json:
             schema: |
               {  "$schema": "http://json-schema.org/schema",
                  "type": "object",
                  "description": "An album",
                  "properties": {                    
          "title": { "type": "string" },
          "artist": { "type": "string" },
          "label": { "type": "string" },
          "year": { "type": "integer" }
         },
         "required": [ "title", "artist" ]
                }
    example: |
                { "title": "Dubnobasswithmyheadman",
         "artist": "Underworld",
         "label": "Junior Boy's Own",
         "year": 1994
                }

Here we’re demonstrating a successful response – i.e., one with an HTTP response code of 200. What we’re interested in specifically is the response body, although you can also define any response headers here too. We then drill down into the available response types; in this case, we’re just representing JSON – though you’re free to define multiple response types if your API supports them.

Once we get down to a successful response’s body, we specify two properties; schema and example.

The schema property contains a JSON schema which defines the structure of the expected JSON. I’ll be covering JSON schema in another article very soon. The example property contains just that, making it clear what sort of response someone calling your API can expect.