Api-blueprint: Response without body, description?

[basickarl]

I'm trying to set a description to a response that does not send a body:

Isn't working:

+ Response 200 (application/vnd.api+json)

    Received on successful update or insert.

This works though:

+ Response 400 (application/vnd.api+json) 

    Received on malformed JSON in the request.

    + Attributes
        - errors (array[Malformed JSON])

[YamiOdymel]

+ Response 200 (application/vnd.api+json)

    Received on successful update or insert.

    + Body

Add an empty body.

[ixti]

@YamiOdymel Thank you sir!

Would be awesome to be able avoid such hacks though IMO.

[FranklinYu]

Strictly speaking, an empty body is not a valid JSON. I use {} instead, but you may prefer null.

[ixti]

@franklinyu Empty string is not a valid body for JSON indeed. Strictly speaking, null is not valid JSON either. Valid JSON must have either key/value collection (even empty one, e.g. {}) or a list (also might be empty one, e.g. []).

But, in the issue we are talking about JSON API which allows empty bodies. JSON API utilizes JSON for non empty bodies, but it's NOT JSON. It's scope is wider than just data serialization format.

UPDATE: Somehow information on json.org is a bit misleading, null is a totally valid JSON according to ECMA specs. So any value (object, array, string, number, true, false, null) is a valid top-level citizen of JSON.

[FranklinYu]

@ixti I have heard of the JSON API but not familiar with it; I skimmed through its specification but didn't find keywords like "empty body".

[ixti]

@franklinyu Take a look on responses description:

• http://jsonapi.org/format/#crud-updating-relationship-responses-202
• http://jsonapi.org/format/#crud-updating-relationship-responses-204

More than that. You SHOULD NOT send body with 204 response according to HTTP specs as well.

[FranklinYu]

For empty body in that case, I prefer not to specify content type at all. Clients should not depend on content type in "204 No Content" response. I think I'm getting off topic…