22

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

Mendhak
  • 7,168
  • 3
  • 46
  • 58

2 Answers2

12

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.

Zdenek
  • 3,523
  • 25
  • 34
  • I see - so I can't specifically create a description/response for /thing/40. Could I submit a feature request for this somewhere? – Mendhak Jan 24 '14 at 08:31
  • 1
    Not in a structured way. You can only comment on it "by mouth". May I ask you what is your use-case / why do you need it? – Zdenek Jan 26 '14 at 09:43
  • 3
    Plan is to add support for it in a future revision of API Blueprint mainly to improve testability of a blueprint – https://github.com/apiaryio/api-blueprint/issues/21, https://gist.github.com/zdne/01e287fe18d232672d43#new-payload-structure-in-1b You can see & contribute to API Blueprint roadmap at https://github.com/apiaryio/api-blueprint/issues/milestones – Zdenek Jan 26 '14 at 09:46
  • 3
    Multiple request/response pairs are now available as ["Multiple Transactions"](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#example-multiple-transaction-examples) in the API Blueprint specification. – bernhardw Sep 15 '14 at 19:39
1

You can use the templates and specify a specific use case after a generic response for your resource, see example:

Reservation [/reservation/{reservation_key}]

A Reservation object has the following attributes:

  • room_number
  • reserved_at - An ISO8601 date when the question was published.

  • booker_details - A Booker Object.

  • Parameters

    • reservation_key (required, text, 1) ... Reservation Key ash

View a Reservation Detail [GET]

  • Response 200 (application/json)

    {
    "room_number": 55,
    "reserved_at": "2014-11-11T08:40:51.620Z",
    "booker_details": 
        {
            "name": "Jon",
            "last_name": "Doe",
        }
}

Reservation [/reservation/notarealreservation123]

Using a non existing reservation (pls use notarealreservation123 in the fake) returns not found

Bizmate
  • 1,718
  • 1
  • 14
  • 18