Handling multiple actions on a single resource

The basic blueprint format allows you to perform a single response to a single request on a one resource.

If you are responding differently based on parameters / query string arguments, you should use Apiary Help: URI Templates.

However, you might want to describe a variety of error or edge cases a resource might respond with.

API Blueprint (FORMAT: 1A) syntax

You can write multiple Request(s) and/or Response(s). It is especially suitable for handling multiple types of Content-Type header.

# Message [/messages/{id}]
This resource represents one particular message identified by its *id*.

## Retrieve Message [GET]
+ Response 200 (application/json)

        {"message":"Hello World!"}

+ Response 200 (text/plain)

        Hello world!

+ Response 401 (text/plain)

        There is no such a message for you, dear guest.

+ Response 410

        The message you are searching for does not exist anymore.

## Delete Message [DELETE]
+ Response 204
For more illustration and use cases explore the raw-view of each example in API Blueprint repository.

Invoking non-default responses


Of course, in some cases, you want to have those responses be returned to client.

First, mock server handles content-negotiation. In the case above, just send

Accept: text/plain

and we'll return proper OK response.

This is not enough for testing error responses, though. For them, you have to use Prefer header.

When testing the above case, put

Prefer:status=401

in your request and mock server will handle you properly.

When trying to choose the right response to given real request, mock server also looks at arbitrary headers. In case both the real request and the request definition from blueprint have particular headers, but their values do not match, those two requests are considered as not matching and mock server will try to choose from different responses.

During response selection, mock server currently does not look at the body of requests at all.

Apiary Blueprint (legacy) syntax:

You can do that by separating possible responses with five plus signs:

POST /shopping-cart
> Content-Type: application/json; charset=utf-8
{ "url": "/shopping-cart/1", "product":"2ZY48XPZ", "quantity": 1, "name": "New socks", "price": 1.25 }
< 201
+++++
< 401
< Content-Type: application/json; charset=utf-8
{"message":"You have not provided proper request token"}
+++++
< 403
< Content-Type: application/json; charset=utf-8
< X-Rate-Limit-Remaining: 0
{"message":"Too many requests, please try again later (see X-Rate-Limit-Remaining header)"}
+++++
< 418
{"message":"Teapot, seriously?"}
+++++
< 451
<message>Legally restricted, sorry</message>

Please note that for now, only the first defined response is always used as a response from mock server or as a base for diff in inspector.

Use-case covered?

Does this cover your use-case? Please let us know using your vote or comment. Also see related ideas:

Feedback and Knowledge Base