0

Chapter 9.5 POST of the HTTP/1.1 spec includes the sentence:

If a resource has been created on the origin server, the response SHOULD be 201 (Created) and contain an entity which describes the status of the request and refers to the new resource, and a Location header

It is referenced frequently. The itention is clear, but I have issues with the meaning of some of the chosen words.

What does "contain an entity which describes the status of the request and refers to the new resource" exactly mean?

How shall the entity (entity-header fields and entity-body) describe the status of the request? Isn't the status of the request 201 (Created)? Whow shall this status be described? Does "describe the status of the request" mean the result, in other words the current entity status?

Thinking of a Web API with JSON representation does it mean that the entity should be included in a JSON representation after a successful POST that created an entity? Thinking of a created image, should the image data be returned in the response body?

What is meant with refers to the new resource? The uri is already in the location header. Shall it be repeated in the body or does it mean just to add an id?

Is there a good source with examples of different entities and its responses to a creation POST?

M. Koch
  • 525
  • 4
  • 20
  • Right after I posted this, Google provided suddendly another result: https://stackoverflow.com/questions/1860645/create-request-with-post-which-response-codes-200-or-201-and-content The examples clearified a lot. This is what I was looking for. It also showed a reference as a relative link. It also lead to another sub-question: Must the location header always include an absolute URI? There I found this: https://github.com/expressjs/express/issues/1809 – M. Koch Apr 12 '22 at 13:44
  • I also found this, so a realtive URI is now allowed: https://en.wikipedia.org/wiki/HTTP_location – M. Koch Apr 12 '22 at 14:24

1 Answers1

1

I think it varies based on the resource you're creating, suppose your posting to a /profile/ resource maybe a payload containing multiple profile fields to update - your return would indicate it was successful and include a reference to the fields you posted (it can even return the entire profile attributes with fields you've updated including all fields);

Another example in the image sense, suppose you are posting a Base64 encoded image to a service that stores the image, the response should show the status (ie: accepted, rejected, file too larage, MIME type accurate or not, etc.) - and within the returned payload if successful you'd want the response to not be vague but return the path and/or filename of the image uploaded;

The header returns the response code - the body returns information related to the invoked action's entity response (it can be a set of fields, a URL, a useful response that when parsed back it can be actionable or informative);

These are principles of good coding, but also keep note of security and not to expose anything in a return that could potentially be damaging for example; when creating a service you want to be clear and provide concise and useful returns so when the client consumes the API it knows what to do, what to expect, etc.

Ilan P
  • 1,602
  • 1
  • 8
  • 13