RFC 5789: Content-Location header usage

[prokhorovn]

The RFC 5789 describes the appropriate usage of Content-Location header in PATCH:

A response to this method is only cacheable if it contains explicit freshness information (such as an Expires header or "Cache-Control: max-age" directive) as well as the Content-Location header matching the Request-URI, indicating that the PATCH response body is a resource representation.

So, it means, that Content-Location header must appear only if the actual representation is the part of response body for PATCH.

Also the usage of Content-Location is mentioned in another RFC 7231:

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.

So, accordingly to this information in both RFCs, the apropriate usage of Content-Location with state-changing requests are following:
Content-Location must appear in response only if response-body contains the new resourse representation.

But, there is also an example in RFC 5789:

Successful PATCH response to existing text file:

HTTP/1.1 204 No Content
Content-Location: /file.txt
ETag: "e0023aa4f"

The 204 response code is used because the response does not carry a message body (which a response with the 200 code would have). Note that other success codes could be used as well.

Furthermore, the ETag response header field contains the ETag for the entity created by applying the PATCH, available at http://www.example.com/file.txt, as indicated by the Content-Location response header field.

How you can see, there is a Content-Location presented in response with 204 status code (No content). Of course, this response doesn't contain any body as well as new resource representation. This fact adds some ambiguity in Content-Location header description. What is the correct usage of this header?

[mnot]

Discussion at: http://www.w3.org/mid/9E6EE6D9-8907-4C4B-A890-E99CC920F871@mnot.net

[mnot]

We could change references to "payload" in the definition of Content-Location to something like "selected representation data", with appropriate references and prose.

However, 6.3.2. Identification (it'd be a lot clearer if that were "payload identification") identifies a payload by the Content-Location header, so that's a bit weird. We'd have to say something like:

If the response has a Content-Location header field, then the sender asserts that the selected representation is a representation of the resource identified by the Content-Location field-value.

That works, I guess, but I fear it's going to confuse even more people, without good examples and explanation.

The other solution would be to just declare this a bug in the PATCH spec. We should consider folding PATCH into core at any rate...

[reschke]

Isn't it pretty clear that the example is in conflict with https://greenbytes.de/tech/webdav/rfc7231.html#rfc.section.3.1.4.2.p.3:

If Content-Location is included in a 2xx (Successful) response message and its value refers (after conversion to absolute form) to a URI that is the same as the effective request URI, then the recipient MAY consider the payload to be a current representation of that resource at the time indicated by the message origination date.

So it seems to me that the semantics in PATCH are wishful thinking (returning the etag but not the content), and we need an erratum.

[royfielding]

On the one hand, the example is a bit silly because CL only has meaning when there is a payload. OTOH, the definition we have doesn't make any sense for 203-206 and who knows what comes after. Maybe we should just change it to

If Content-Location is included in a 200 or 201 response message …

[mnot]

Maybe the PATCH deleted the representation body.

Seriously though, we should probably file an erratum on PATCH. Unless we want to incorporate it.

I don't have strong feelings about whether or not we limit C-L to status codes that opt into it, as long as new status codes have the option of using it too.

[prokhorovn]

I think the case, when PATCH removes resource isn't possible, it looks to be designed for partial update. I can't imagine case when partial update of something causes deletion of it. In my opinion Roy's approach with limitation for CL header to status codes is a solution. Your concern is: 'limiting CL to 200 and 201 only will block from usage with all new 2xx codes', correct? If so, it could be formulated as "When header used with 2xx status except 203-206...". It will allow to apply CL to all new 2xx codes without modifying document for each and remove the contraversial case with CL for status codes with no payload. Does it make sense? чт, 11 окт. 2018 г., 10:41 Mark Nottingham <notifications@github.com>:

…

Maybe the PATCH deleted the representation body. Seriously though, we should probably file an erratum on PATCH. Unless we want to incorporate it. I don't have strong feelings about whether or not we limit C-L to status codes that opt into it, as long as new status codes have the option of using it too. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#20 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AS4oQUOwQAxQP6BKxNp_pv3p0-ccRUwIks5ujvY0gaJpZM4KCmy7> .

[mnot]

Perhaps, but that still doesn't avoid the issue with PATCH; giving the header special semantics depending on the status code and method in use isn't good practice.

Errata against PATCH reported here.

[reschke]

Now if the erratum was accepted, we could close this issue...

[reschke]

The erratum is now accepted, so I believe we can close this ticket.