Multiple responses

[avigoldman]

Hey team 👋

As I'm reading the spec I'm trying to understand why a httpTransaction can only contain one httpResponse. Any insight you can share there?

[kylef]

That's because it describes a request-response pair. If you want multiple request-response pairs then you could have multiple httpTransactions.

The example’s content consist of a request-response message pair. A transaction example MUST contain exactly one HTTP request and one HTTP response message.

[avigoldman]

Is there a way to have a single request with multiple sample responses?

[kylef]

The idea is, you would provide the request which would cause that specific response. I would gather that your implementation won't randomly provide different responses with same request. It is likely that a request parameter, header or request message body etc would cause the different response. So you would have a different request example which would produce that response. The only exception to this would be infrastructure problems and such where you could get 5xx error codes. The other case may be due to idempotency when calling the same request twice produces different response. For example calling DELETE twice on a resource where first time there is success and second time causes a 404 because it is already deleted. That said, it is probably clearer in your examples to use separate requests which produce it for example a request to delete an existing resource and a separate request example of deleting an already-deleted resource or a resource that doesn't exist.

Here's an example, in API Blueprint where a request with one Authorization header value causes error and when I provide a valid Authorization header I receive a success:

+ Request

    + Headers

            Authorization: invalid token

+ Response 403

+ Request

    + Headers

            Authorization: valid token

+ Response 204