How can I have multiple responses from a single endpoint with different parameters?

Question

We are looking at using the API Blueprint. There are cases where we would like one request to return a proper response and another request to return an 'error' response such as a 400 bad request so that other developers can work against the mock API on apiary.io with both types of responses and handle it in their applications.

I've created a completely arbitrary example below,

## Thing [/thing/{id}]
Gets a thing but the thing id must be a prime number!


+ Parameters
    + id (string) ... ID of the thing, a prime number!

+ Model (application/json)

    The thing itself.

    + Body

            {
                "description": "It is green"
            }

### Retrieve a Single Gist [GET]
+ Response 200

    [Gist][]

Now somehow I would like to add in a response for /thing/40

+ Response 400
    {  "error" : "Invalid request" }

But I am not sure how I would do this with the API Blueprint. This was achievable under the 'old' style on apiary.io but we'd like to move on to the new syntax

Answer 1

To document multiple responses simply add it after the Response 200 like so:

## Thing [/thing/{id}]
Gets a thing but the thing id must be a prime number!

+ Parameters
    + id (string) ... ID of the thing, a prime number!

+ Model (application/json)

    The thing itself.

    + Body

            {
                "description": "It is green"
            }

### Retrieve a Single Gist [GET]
+ Response 200

    [Thing][]

+ Response 400 (application/json)

        {  "error" : "Invalid request" }

Note there is currently no dedicated syntax to discuss the conditions (when this response i s returned). You can discuss it anyway you like it for example:

+ Response 400 (application/json)

    This response is returned when no `Thing` for given `id` exists.

    + Body

If you are using Apiary mock, keep in mind that the first response listed is returned by default, unless you say otherwise using the prefer HTTP header.