Parameters API


In this installment of the API Blueprint course we will discuss how to describe URI 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

Messages

Group of all messages-related resources.

My Message

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 below, where we will also set its example value to 1 and declare it of an arbitrary ‘number’ type.

Retrieve a Message

REQUEST Plain Text Message

Parameters
id number 1

An unique identifier of the message.

Headers
Accept text/plain

RESPONSE

Headers
Content-Type text/plain
X-My-Message-Header 42
200 text/plain
                        Hello World!

                      
                        
                      

REQUEST JSON Message

Parameters
id number 1

An unique identifier of the message.

Headers
Accept application/json

RESPONSE

Headers
Content-Type application/json
X-My-Message-Header 42
200 application/json
                        {
  "id": 1,
  "message": "Hello World!"
}

                      
                        
                      

Update a Message

REQUEST Update Plain Text Message

Parameters
id number 1

An unique identifier of the message.

Headers
Content-Type text/plain
text/plain
                          All your base are belong to us.

                        
                          
                        

RESPONSE

Headers

REQUEST Update JSON Message

Parameters
id number 1

An unique identifier of the message.

Headers
Content-Type application/json
application/json
                          { "message": "All your base are belong to us." }

                        
                          
                        

RESPONSE

Headers
All My Messages

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 possible action of this resource, therefore we will discuss it only at the particular action level below.

Retrieve all Messages

REQUEST

Parameters
limit number
Default
20

The maximum number of results to return.

RESPONSE

Headers
Content-Type application/json
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."
  }
]