Consider labeling responses when an API returns different payloads

[tciuro]

It would be awesome if an API section could specify more than one response with the same status code and label it to differentiate it.

For example, the following API could return two different payloads based on the parameter used:

[/things/something{?foo,bar}]

If I call /things/something?foo=true it may return:

{ "result": "blah" }

If I call /things/something?bar="abc" it may return:

{ [{ "id": 1, "title": "meh" }] }

I'd like to specify two Response sections:

Response 200                                                            ?foo=...
    +body
         { "result": "blah" }

Response 200                                                            ?bar=...
    +body
        { [{ "id": 1, "title": "meh" }] }

This way it would be clear what response payload is associated with each parameter.

[zdne]

Note this may be a limitation in API Blueprint itself. While it is possible to have multiple responses with the same status code every one should be preceded by a request section.

[tciuro]

@zdne indeed, it's possible and gets rendered properly. Thanks!

[jkryanchou]

+1 I'm so looking forward to support multiple responses with same http status code