Location vs Content-Location on post requests-CodePudding

I am confused about the header Location and Content-Location.

Content-Location

Regarding Content-Location I found this statement in the spec. (Emphasis mine)

For a state-changing request like PUT (Section 4.3.4) or POST (Section 4.3.3), it implies that the server's response contains the new representation of that resource, thereby distinguishing it from representations that might only report about the action (e.g., "It worked!"). This allows authoring applications to update their local copies without the need for a subsequent GET request.

However, in the mdn docs is an example that shows the opposite behaviour. (Emphasis mine)

The site returns a generic success message confirming the post was published. The server specifies where the new post is with Content-Location:
HTTP/1.1 201 Created
Content-Type: text/plain; charset=utf-8
Content-Location: /my-first-blog-post

✅ Success!

These two statements seem to contradict each other.

Now, I am unsure if I should use Content-Location for the case of not including the real entity in the response.

Location

The spec has a sentence about the Location header.

For 201 (Created) responses, the Location value refers to the primary resource created by the request.

And mdn is saying the same.

In cases of resource creation, it indicates the URL to the newly created resource.

I am confused which one to pick for a post response that does not include the entity.

I am guessing the Location header would be most appropriate for a generic post request where the entity can be viewed later. For example, posting a user and viewing it.

What about a POST response with a 202 code? For example, when posting a task to a queue where later only the status of the task can be viewed. So it isn't a real entity like a user. I.e. an email was dispatched to X clients based on the posted task, now I want to communicate where the status (PENDING, FAILURE or SUCCESS) can be viewed.

CodePudding user response：

You are correct, and MDN is wrong about the first example. This example:

HTTP/1.1 201 Created
Content-Type: text/plain; charset=utf-8
Content-Location: /my-first-blog-post

✅ Success!

Suggests that the contents of /my-first-blog-post is ✅ Success!, due to the Content-Location header.

Given that you don't want to return the new resource's body, you should keep Location and omit Content-Location.

And if you have time: report the issue to the MDN maintainers.

What about a POST response with a 202 code? For example, when posting a task to a queue where later only the status of the task can be viewed. So it isn't a real entity like a user. I.e. an email was dispatched to X clients based on the posted task, now I want to communicate where the status (PENDING, FAILURE or SUCCESS) can be viewed.

I would suggest a Link header.