Does a HTTP 200 response imply that there must be a response body?

0
votes

I'm attempting to decipher a Swagger specification document and use it to generate code. It contains the following endpoint definition:

/feature:
  get:
    summary: Returns all features
    operationId: getAllFeatures
    tags:
      - feature
    responses:
      '200':
        description: 'Features retrieved successfully'
      '400':
        $ref: '#/responses/BadRequest'

Based on the endpoint summary and the 200 response description, it's pretty clear to me that this endpoint was intended to return a response body that contains an array or collection of "feature", even though the response is not defined in the spec.

Let's suppose that I'm right, and the spec author just forgot to add it. What then should I make of this endpoint:

/features:
  put:
    summary: Updates an existing feature
    operationId: updateFeature
    parameters:
      - name: body
        in: body
        description: 'Feature to be updated'
        required: true
        schema:
          $ref: '#/definitions/Feature'
    tags:
      - feature
    responses:
      '200':
        description: 'Feature updated'

This one is ambiguous to me. I've seen some implementations of update endpoints that return the updated object. Others I've seen return nothing in the body.

My questions are this:

  1. Does a HTTP 200 response imply there must be a response body? I can't tell whether the HTTP specification (https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) requires this or if it just states that it could be there.
  2. Would it be less confusing in this scenario for the spec author to have used HTTP 204 to expressly indicate that there is no response body? (I can answer this - yes - but are there reasons to use HTTP 200 instead of 204 in this case? Or was this just that the author didn't know about success response codes other than HTTP 200?)
  3. If the answer to #1 is no, and the answer to #2 is yes: why was HTTP defined in this manner?
1
httpswaggeropenapi

1 Answers

2
votes
  1. 200 OK can return an empty body with Content-Length: 0.
  2. 204 No Content has a more specific purpose than many people realize. Quote from the current spec:

The 204 response allows a server to indicate that the action has been successfully applied to the target resource, while implying that the user agent does not need to traverse away from its current "document view" (if any). The server assumes that the user agent will provide some indication of the success to its user, in accord with its own interface, and apply any new or updated metadata in the response to its active representation.

Basically this is saying, if for example a HTML form is submitted, and the server responds with 204, it can signal a browser to not refresh the current page to the new location, or redirect anywhere else. It can for example facilitate a 'save' action without forcing the browser to redirect/switch to a new url. Also see 205 for a similar action, but with different behavior.

Browsers (as far as I know) don't actually implement this behavior. But a REST/Hypermedia/HATEOAS client could.

The current spec also states the more common use, which is 200 without a response body, but if you go all the way back to the HTTP/1.0 spec, this is the entire section. Notice that it only mentions this behavior, and says nothing about 204 being just a substitute for 200 minus body:

The server has fulfilled the request but there is no new information to send back. If the client is a user agent, it should not change its document view from that which caused the request to be generated. This response is primarily intended to allow input for scripts or other actions to take place without causing a change to the user agent's active document view. The response may include new metainformation in the form of entity headers, which should apply to the document currently in the user agent's active view.

So the key here that this signals about how a hypermedia client should behave. removing that, I would agree there's not a lot of reasons to use 204. It's become a convention that I don't think has a strong purpose.

Sidenote: don't refer to RFC2616 unless you're into internet archeology.

  1. See #2