RAML: THE RESTFUL API MODELING LANGUAGE (PART 6)

Query Parameters:

We can define query parameters (typically for GET requests) in a very similar manner in which we defined URI parameters.

To illustrate, let’s look again at our /albums endpoint, supposing that we wanted to implement pagination; so, we probably want to provide a query parameter named page which allows the requesting party to specify which page they want to retrieve.

Here’s how we might do that:

/albums:
  get:
    description: Retrieve a list of albums
    queryParameters:
      page:
        description: Specify the page that you want to retrieve
        type: integer
        example: 1

Again, the definition of the query parameter is a mixture of meta-information – such as the descriptionand an example – and some properties which help explicitly define what the API expects; here we’re making it clear that the page parameter should be an integer.