REST API 200 & 201 Body responses

Question

Problem I am writing a API standards document for my firm and have been trying out various tools to enhance our API lifeycle, today I have tried out an API definition security validation tool from apisecurity.io, it highlighted an interesting error with one of my POST operations: “You have not defined any schemas for responses that should contain a body.” Link:Response schema undefined and references RFC 7231

The API endpoint that was flagged was a POST operation that returned: A 201 status code, a Location header but no body. (Hence the error as the tool is expecting all 200s codes to have a body except for 204)

Research The RFC7231 Section 6.3.2 states:

The 201 (Created) status code indicates that the request has been fulfilled and has resulted in one or more new resources being created. The primary resource created by the request is identified by either a Location header field in the response or, if no Location field is received, by the effective request URI.

The 201 response payload typically describes and links to the resource(s) created. See Section 7.2 for a discussion of the meaning and purpose of validator header fields, such as ETag and Last-Modified, in a 201 response.

Also when looking at what RFC7231 Section 4.3.3 defines for POST operations when the operation resulted in a resource being created, it states:

If one or more resources has been created on the origin server as a result of successfully processing a POST request, the origin server SHOULD send a 201 (Created) response containing a Location header field that provides an identifier for the primary resource created (Section 7.1.2) and a representation that describes the status of the request while referring to the new resource(s)."

Interpretation When a POST results in a successful creation of a resource:

HTTP 201 should be returned
Location header should be returned with the URL of the newly created resource
A "representation that describes the status of the request while referring to the new resource"

The top two are neither a surprise but the third one is where I find conflicting guidance from what the standards ask for and what is available as a precedent. From my research, Google, Paypal, Github and Stripe, all reputable API creators, send a full representation of the newly created resource and not a "representation of the status of the request".

Is the RFC wrong / out of date and the best practice is that we should return the full body? I would really value input from others who have encountered / debated this or is interested in the conversation.

It might seem a trivial question but I am trying to document the best practice to drive our consistency forward similar to Zalendo (also appear to return the resource unless a 204 is returned but in that case the client doesnt know if the resource was created or if it was updated by the POST)

Question to answer Is there a standard to follow for response bodies of this type?

The same answer could apply to a PUT or POST getting a 200 response or a PUT getting a 201.

user_54734 · Answer

Is the RFC wrong / out of date and the best practice is that we should return the full body? I would really value input from others who have encountered / debated this or is interested in the conversatio

The RFC is, as far as I can tell, fine.

The idea I think you are missing is Content-Location, which is to say that we can use meta data in the response to make clear, in a standardized way, what the representation we are sending back from the server is.

A typical "representation of the status of the action" might look like

201 Created
Location: /api/new-things/12345

Your document can be fetched from /api/new-things/12345

If instead we want to send a representation of the new document (resource) we created, then we need to signal that in the meta data.

201 Created
Location: /api/new-things/12345
Content-Location: /api/new-things/12345

Hi, I'm your new document, which can be fetched from /api/new-things/12345

Roughly - yes, you can just send the representation of the new thing you created on the server, and your bespoke client can understand that. But we also have the problem that general-purpose components need to understand the conversation as well, and as far as they were concerned, we were having a conversation about the target-uri, not about /api/new-things/12345.

The HTTP standard is about describing what is going on using the semantics that are common to all resources and components, not your specific bit of java script talking to your specific URI.

user_6546771 · Answer

Using the PUT or POST response to return the updated resource representation rather than the status is commonplace and the APIs you listed are good examples of this. I suppose the rationale for this is to offer some convenience for the client developer.

It's not what is described in the HTTP spec (confirmed by the quotes you gave), and doing this limits the richness of the API.

For example an API may accept valid documents that comply with the schema, but perform business rules assessment or trigger a series of events. The response status is there to let the client know what happened and any problems that occur from a business rules perspective. Note that 40x responses are to do with client errors not user errors.

My view is then to provide a status document listing useful information about such processing including

Business rule evaluation status and results (with links)
Events raised
Actions performed in addition to the storage of the document
Transaction ids for tracing and reference
Timestamps for the document and / or version numbers.
Key data items generated or matched such as tags, ids, keys etc that may be of note.

I am not aware of any standard JSON document formats for this (akin to application/problem+json see https://www.rfc-editor.org/rfc/rfc7807), however perhaps one would be useful e.g. application/processing+json to tighten up API responses in this area.

REST API 200 & 201 Body responses

2 Answers