Collection update API » History » Revision 2
Revision 1 (Peter Amstutz, 05/18/2015 09:13 PM) → Revision 2/5 (Peter Amstutz, 05/19/2015 01:26 PM)
h1. Collection update API Problem: adding, updating, renaming, or removing a file in a collection requires sending the entire manifest text of the collection. This approach creates two problems: # It is inefficient; resources are wasted transferring and processing manifest data that hasn't changed # It creates a race condition; for example processes A and B read the collection record at time T1, merge it with their local updates, process A sends its update at time T2, process B sends its update at time T3; this causes T3, then in process A's updates to be dropped. are lost. Proposed solution: introduce new 'update' or 'patch' endpoint for collections supporting a patching protocol allowing incremental collection update. The protocol consists of two fields: an *operation* field with values of *add*, *remove* or *modify*. Each operation has parameters *initial_contents*, and *add*. *final_contents*. Each field contains a fragment of manifest text. The *remove* field lists files that should be removed from the collection. *contents* fields contain normalized manifests with exactly one file. Remove is processed before add. For each file, check that the The stream and file in the collection has the same content (== same blocks/segments) as the file name are put together to be removed. If get the file contents match, name of the file that is removed. If affected by the file in tho collection file does not match the file to be removed, the file in the collection is renamed to operation. An *add* operation adds a new unique name that indicates it is in conflict. file represented by *final_contents*. If the file is not present in the collection, do nothing. The *add* field lists files that *initial_contents* should be added to the manifest. empty or unspecified. If there is already a file does not exist in with that name and the collection, it is added. If the existing file already exists in has different contents, the collection, the existing file in the collection is should be uniquely renamed to a new unique name indicate that indicates it is in conflict; conflict, and the new file is put in takes its place. After the patch call, respond with the portable data hash. The caller can compare the PDH to the expected result to determine if there were conflicts that require it to update its local collection contents. Any other files in the collection that are not mentioned in the An *remove* or *add* operations are unaffected. With this protocol we can implement add, delete, rename, modify, and combine collections: * add: provide one or more files to be added in the *add* field * remove: provide one or more files to be removed in the *remove* field * rename: list the file with the old name in the *remove* field and the new name in the *add* field * modify: list the file with the old contents in the *remove* field and the new contents in the *add* field * combine collections: provide the full collection manifest in the *add* field adds