thehabes
commented
7 years ago I definitely think 1 (JSON Patch) is the best choice for us. My main arguments against JSON Merge are thus:
Passing null as a value to any key removes it from the JSON. This means if there is any error on the client that results in a null when performing a JSON Merge request, the resulting JSON object in your data may not be what you expect because keys could be dropped.
Also, this statement from the documentation:
There are a few things to note about the [Merge] function. If the patch is anything other than an object, the result will always be to replace the entire target with the entire patch (client requests errors can be catastrohpic). Also, it is not possible to patch part of a target that is not an object, such as to replace just some of the values in an array.
Think of otherContent[], AnnotationLists.resources[], Ranges[], images[] where often we want to replace just a part of an array, either due to removal, addition to a specific index or reordering. If the request is to always contain the full updated array to replace the target, then it's not a problem, but it's a decision set in stone. You have experienced this style with our current annotation store, we pass in entire arrays meant to be replacements for their target. You would never be able to do something like, for example, mongo $push and $pull type operations.
To me, json patch can get bulky and complex, as the format for making the request is quite expansive, whereas JSON merge just wants your object, which is nice. However, add-remove-update is explicit with json patch and fails or peculiarities from the client requests inherently have a better fail safe. The values with json patch do fit the way we store id's url style, which is a plus.
These may be terrible arguments and not actually matter, but it's what stands out to me from comparing the two. For what it's worth, JSON Patch seems to have more libraries of code that can be used, where JSON Merge just has Java, which is something to consider. My guess is we would use the Java implementations, and both are something I understand and can manage with whatever code we bundle it with.
cubap
There seem to be two good ways to support partial updates on RERUM.
both has good libraries and support. In the first, you send the object with only the properties to be changed or null for deletions. It works, but may get confusing with complex objects. The second requires a JSON document that is essentially a list of instructions for the patch. It is a thing the API user has to generate, which maybe isn't great, but the intention is always clear and for big documents, it can be more lightweight.
I'm not sure which to support and both is down the line a bit, since it is real work to do either.