selecting_from_multuple_responses.md

FORMAT: 1A

HOST: http://www.google.com

Parameters API

In this installement of the API Blueprint tutorial we will discuss how to describe API parameters. But first let's add more messages to our system. For that we would need introduce an message identifier – id. This id will be our parameter when communicating with our API about messages.

API Blueprint Tutorial

• Previous: Requests
• This: Raw API Blueprint
• Next: Headers

Group Messages

Group of all messages-related resources.

My Message [/message/{id}]

Here we have added the message id parameter as an URI Template variable in the Message resource's URI. Note the parameter name id is enclosed in curly brackets. We will discuss this parameter in the Parameters section bellow, where we will also set its example value to 1 and declare it of an arbitrary 'number' type.

• Parameters
  • id (number, 1) ... An unique identifier of the message, ok?

Retrieve a Message [GET]

Retrieve descrition

• Request Plain Text Message

  • Headers

      Accept: text/plain
    

• Request Not exists

  • Headers

      Preferred: 404
    

• Response 200 (text/plain)

  • Headers

      X-My-Message-Header: 42
    

  • Body

      Hello World!
    

• Request JSON Message

  • Headers

      Accept: application/json
    

• Response 200 (application/json)

  • Headers

      X-My-Message-Header: 42
    

  • Body

      { 
        "id": 1,
        "message": "Hello World!" 
      }      
    

• Response 404

  • Headers

      X-My-Message-Header: 42
    

  • Body

      Not found.      
    

Update a Message [PUT]

Update description

• Request Update Plain Text Message (text/plain)

    All your base are belong to us.
  

• Request Update JSON Message (application/json)

    { "message": "All your base are belong to us." }
  

• Response 204

All My Messages [/messages{?limit}]

A resource representing all of my messages in the system.

We have added the query URI template parameter - limit. This parameter is used for limiting the number of results returned by some actions on this resource. It does not affect every possiblle action of this resource therefore we will discuss it only at the particular action level bellow.

Retrieve all Messages [GET]

All messages retrieval description

• Parameters

  • limit = 20 (optional, number) ... The maximum number of results to return.

• Response 200 (application/json)

    [
      {
        "id": 1,
        "message": "Hello World!"
      },
      {
        "id": 2,
        "message": "Time is an illusion. Lunchtime doubly so."
      },
      {
        "id": 3,
        "message": "So long, and thanks for all the fish."
      }
    ]