So far Astoria has used \u201cmerge\u201d semantics for update. That is, an \u201cupdate\u201d operation (an HTTP PUT request) replaces the values of the properties for the target entity that are specified in the input payload; this applies both to properties and links. If a property or link is not present in a PUT operation, it means \u201cleave it with its current value\u201d. To null-out a property or link it has to be present in the PUT body and has to have a null marker (null attribute for properties, null href for links). <\/p>\n
While supporting merge is important and will remain part of Astoria, there are scenarios where we need \u201creplace\u201d semantics. That is, an operation where the entity properties are entirely replaced by those in the request body, even if the request body is partial. In particular, the AtomPub protocol requires PUT to have replace semantics. <\/p>\n
Operation semantics<\/b> <\/p>\n
In a \u201creplace\u201d operation, each property in the target entity either takes the value specified in the payload (if any) or its default value. The meaning of \u201cdefault value\u201d for a \u201creplace\u201d operation is server implementation-specific. The Astoria server will likely use the CLR default values for each value type and null for references. <\/p>\n
For operations on primitive values (e.g. PUT \/Customers(123)\/CompanyName), there is no practical difference between \u201cmerge\u201d and \u201creplace\u201d. <\/p>\n
A \u201creplace\u201d operation, just like a \u201cmerge\u201d operation, cannot specify different values in the key properties. That is, keys remain non-updatable in \u201creplace\u201d. Similarly, a \u201creplace\u201d operation is subject to the same requirements from the ETags perspective as a \u201cmerge\u201d operation. <\/p>\n
About links inside entity payloads: \u201creplace\u201d operations replace the properties in entities themselves, not its links. If you include a link in a \u201cmerge\u201d or \u201creplace\u201d operation we\u2019ll wire it up, but if you don\u2019t it\u2019ll maintain the existing links. <\/p>\n
About directly-addressed links: links are currently atomic values (just the link itself), so there is no difference between replacing it and merging it when operating on link resources (e.g. \/$links\/\u2026). Astoria servers should support both operations but keep identical semantics. The rest of this discussion won\u2019t touch on links as stand-alone resources anymore. <\/p>\n
Note that these operational semantics are the same regardless of the actual format (Atom, JSON, etc.) used to represent the resources being exchanged. <\/p>\n
Finally, this in general does not apply to service operations, as the meaning of service operations is service-defined. It\u2019s interesting to think about whether in the Astoria server library we introduce some mechanism to allow it to expose a MERGE-enabled URL, but that would still require the user-implementation to make sense of it. <\/p>\n
HTTP interface<\/b> <\/p>\n
AtomPub specifically requires HTTP PUT to mean replace. So we adjusted the way Astoria interprets PUT to mean \u201creplace\u201d. <\/p>\n
In order to request a \u201cmerge\u201d operation we have two options: <\/p>\n
1. Introduce a new HTTP method, \u201cMERGE\u201d, and rely on verb tunneling (POST + a header) for the cases where custom methods are not allowed. There has been talk about a PATCH verb in multiple circles including the AtomPub community, but it seems to be going in a somewhat different direction. <\/p>\n
2. Introduce a new custom header, \u201cDataServices-Merge\u201d or something, that when set to \u201c1\u201d in a PUT request indicates that the server should merge the body with the server entity instead of replacing it. <\/p>\n
While we\u2019re not thrilled with the idea of introducing a new HTTP method, overloading PUT with an extra header seems to be very problematic. If anything else, a server that does not support \u201cmerge\u201d through headers would see PUT as a regular \u201creplace\u201d request and perform an operation that\u2019s not what the client expected. Also other things break. For example, if a server sees an actual MERGE request and cannot handle it then it can respond with 405 \u2013 method not supported. <\/p>\n
So we\u2019re leaning toward MERGE and tunneling (we already support tunneling for PUT\/DELETE in Astoria servers and clients). <\/p>\n
Responses to \u201cmerge\u201d and \u201creplace\u201d requests are identical. <\/p>\n
.NET client<\/b> <\/p>\n
Using \u201cmerge\u201d from the client has several advantages: <\/p>\n
1. The server does not know what a client considers a \u201cwhole\u201d entity. The client may be using entity types that contain a subset of the properties of the server-side version, either due to versioning mismatches or because the client is not interested in all of the properties. <\/p>\n
2. The client is pretty much required to use \u201cmerge\u201d to make links work. Since an entity might have been brought down to the client without its related entities expanded, one or more links won\u2019t be present, and if we used replace we\u2019d lose information on the server. <\/p>\n
Based on the above, it would seem that the client should do \u201cmerge\u201d, which will effectively result in \u201creplacing the subset the client knows about\u201d because the client always sends all the fields. <\/p>\n
The problem now is servers that don\u2019t implement \u201cmerge\u201d operation. One option is to require \u201cmerge\u201d for the client to work, but that leaves too many interesting scenarios out. Since we already had a SaveChangesOptions enum that\u2019s used as an argument to SaveChanges\/BeginSaveChanges, we introduced SaveChangeOptions.UpdateAsReplace to indicate that you want the client to use PUT. <\/p>\n
AJAX client<\/b> <\/p>\n
The AJAX client\u2019s DataService.update method can be extended with a new argument \u201cUpdateAsReplace\u201d that enables use of replace when set to true. By default we would continue to do \u201cmerge\u201d (this requires tweaking the library because currently DataService.update generates a PUT request). <\/p>\n
If the new boolean adds one too many arguments for update(), alternatively we could add a knob to the DataService class, we still made this change. <\/p>\n
Astoria runtime-data source interaction<\/b> <\/p>\n
The only change in the interaction between Astoria and the data source should be that for the resource being replaced the system will call IUpdatable.ReplaceResource instead of IUpdatable.GetResource. <\/p>\n
Pablo Castro
Software Architect
Microsoft Corporation <\/p>\n