Can I provide multiple example responses?

Question

I'm writing a spec for an API where the fields included in the response vary. I would like to be able to provide more than one example to show this. My use cases are:

1. One of the API calls has an include parameter which allows the user to specify some additional fields to be included in the response
2. For some API calls, the fields included in the response depend on permissions associated with the user's API key

What I'd like to be able to do is something like this:

+ Response 200 (application/json)

    {
      "id": 1, 
      "name": "Joe Bloggs",
      "email": "[email protected]"
    }

+ Response 200 (application/json)

  If `include=telephone` was specified:

    {
      "id": 1, 
      "name": "Joe Bloggs",
      "email": "[email protected]",
      "telephone": "0123456789"
    }

+ Response 200 (application/json)

  If the API key has access to address data:

    {
      "id": 1, 
      "name": "Joe Bloggs",
      "email": "[email protected]",
      "address": [{
          "address1": "101 My street",
          "address2": "My area"
      }]
    }

As far as I can tell, although you can provide multiple responses, you can only do so if the response code or content type differ. Is there any way to do this?

Answer 1

Update: This has already been implemented see the API Blueprint Specification.

---

Original answer:

TL;DR: Not supported, planned

As far as I can tell, although you can provide multiple responses, you can only do so if the response code or content type differ.

Your findings are indeed correct. There is currently no way to do this. I was pondering this idea a lot lately. The solutions seems to be lift this restriction and implement the implicit transaction examples – Automatic request response pairing.

Note that in your case this seems to me like two different transaction examples based on the request

(pseudocode):

Example 1: 
- Request With Phone Number
- Response With Phone Number 200 (application/json)

Example 2: 
- Request Default
- Response Default 200 (application/json)

Assuming include=telephone is a URI query parameter this planned feature will need next to the automatic pairing also the syntax for describing URI parameters values.