Improper POST behavior in Document APIs

[canweriotnow]

If an Activity Provider stores variables as JSON Objects in a document with content type application/json, they can manipulate them as sets of variables using POST.
When an LRS receives a POST request with content type application/json for an existing document also of content type application/json, it MUST merge the posted document with the existing document.

This is a violation of expected behavior for RESTful APIs; POST should ONLY be used to create a new resource; PUT should replace an existing identified resource.

A partial update to an existing resource should use the PATCH method as described in RFC 5789.

[garemoko]

I think this needs to be re-tagged as major.

[fugu13]

No, this is not a violation of the expected behavior for RESTful APIs. From the horse's mouth:

But why shouldn’t you use POST to perform an update?

http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post

[fugu13]

Additionally, the 'partial document update' we are doing here is not suitable for PATCH, as described in the very RFC you linked and explicated at http://williamdurand.fr/2014/02/14/please-do-not-patch-like-an-idiot/ . PATCH is for instructions on how to update content, not just partial updates (which, as Roy lays out in the earlier article I linked, is perfectly fine to do via POST, like we currently are). We could start using PATCH, but it would be a different function from what we're using POST for right now.

[thomasturrell]

Since this issue is still open I thought it was worth commenting on.

I have observed that at least one xAPI client implementation assumes that POST is used to create a new resource and that PUT is used to replace an existing resource. In 2023 it seem like that is quite a common assumption. Rightly or wrongly many API's work this way.

In my opinion, an LRS merging a posted document with the existing document doesn't seem to have much practical use. I don't think that removing this requirement would be an issue.