Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revisionBoth sides next revision
dev:web_api:v3:syncing [2019/03/10 04:22] – [Full-Library Syncing] dstillmandev:web_api:v3:syncing [2019/03/10 04:38] – dstillman
Line 14: Line 14:
   * A version number for each library   * A version number for each library
   * A version number and a boolean ''synced'' flag for each syncable object   * A version number and a boolean ''synced'' flag for each syncable object
 +  * A flag indicating that a downloaded object could not be processed and should be requested explicitly regardless of its remote version number (optional; see [[#Handling save errors|Handling save errors]] for details)
  
 ===== Version Numbers ===== ===== Version Numbers =====
Line 68: Line 69:
  
 Like ''format=keys'', ''format=versions'' is not limited by a maximum number of results and returns all matching objects by default. Like ''format=keys'', ''format=versions'' is not limited by a maximum number of results and returns all matching objects by default.
 +
 +=== Local object versions ===
 +
 +The use of local object versions during syncing, and the process for updating them, is described below.
 +
 +When objects are created or modified locally by the user during regular usage, set ''synced = false'' to indicate that the object needs to be uploaded on the next sync. Give new objects version 0. Do not change the version when objects are modified outside of the sync process.
  
 ===== Full-Library Syncing ===== ===== Full-Library Syncing =====
Line 139: Line 146:
 Retrieve the versions of all objects changed since the last check for that object type, using the appropriate request for each object type: Retrieve the versions of all objects changed since the last check for that object type, using the appropriate request for each object type:
  
-  GET <userOrGroupPrefix>/collections?since=<last saved library version>&format=versions +  GET <userOrGroupPrefix>/collections?since=<version>&format=versions 
-  GET <userOrGroupPrefix>/searches?since=<last saved library version>&format=versions +  GET <userOrGroupPrefix>/searches?since=<version>&format=versions 
-  GET <userOrGroupPrefix>/items/top?since=<last saved library version>&format=versions&includeTrashed=1 +  GET <userOrGroupPrefix>/items/top?since=<version>&format=versions&includeTrashed=1 
-  GET <userOrGroupPrefix>/items?since=<last saved library version>&format=versions&includeTrashed=1+  GET <userOrGroupPrefix>/items?since=<version>&format=versions&includeTrashed=1
  
-''<last saved library version>'' is the ''[[#last-modified-version|Last-Modified-Version]]'' returned from the API for the last successfully completed sync process, or ''0'' when syncing a library for the first time.+''<version>'' is the ''[[#last-modified-version|Last-Modified-Version]]'' returned from the API for the last successfully completed sync process, or ''0'' when syncing a library for the first time.
  
 (The ''since'' parameter can also be used on ''.../tags'' requests (without ''format=versions'') by clients that don't download all items and wish to keep a list of all tags in a library up-to-date. It isn't necessary for clients that download all items to request updated tags directly, as item objects contain all associated tags.) (The ''since'' parameter can also be used on ''.../tags'' requests (without ''format=versions'') by clients that don't download all items and wish to keep a list of all tags in a library up-to-date. It isn't necessary for clients that download all items to request updated tags directly, as item objects contain all associated tags.)
Line 162: Line 169:
 For each returned object, compare the version to the local version of the object. If the remote version doesn't match, queue the object for download. Generally all returned objects should have newer version numbers, but there are some situations, such as full syncs (i.e., since=0) or interrupted syncs, where clients may retrieve versions for objects that are already up-to-date locally. The version will also match for top-level items on the second, non-'/top' ''items'' request, since top-level items will have already been processed. For each returned object, compare the version to the local version of the object. If the remote version doesn't match, queue the object for download. Generally all returned objects should have newer version numbers, but there are some situations, such as full syncs (i.e., since=0) or interrupted syncs, where clients may retrieve versions for objects that are already up-to-date locally. The version will also match for top-level items on the second, non-'/top' ''items'' request, since top-level items will have already been processed.
  
-Retrieve the queued objects by key, up to 50 at a time, using the appropriate request for each object type:+Retrieve the queued objects, as well as any [[#Handling save errors|flagged]] as having previously failed to save, by key, up to 50 at a time, using the appropriate request for each object type:
  
   GET <userOrGroupPrefix>/collections?collectionKey=<key>,<key>,<key>,<key>   GET <userOrGroupPrefix>/collections?collectionKey=<key>,<key>,<key>,<key>
Line 197: Line 204:
              
  
-If an error occurs while processing an object (e.g., due to a foreign-key constraint in a database), it can be handled one of two ways:+== Handling save errors == 
 + 
 +If an error occurs while processing an object (e.g., due to a foreign-key constraint in the local database), it can be handled one of two ways:
  
   - Treat the error as fatal and stop the sync without updating the local library version   - Treat the error as fatal and stop the sync without updating the local library version
Line 203: Line 212:
  
 When processing a set of objects, it may be helpful to maintain an object queue and add failing objects to the end of the queue in case they depend on other objects to succeed. (In some cases, it's also possible to sort objects beforehand to avoid such errors, such as by sorting parent collections before subcollections.) When processing a set of objects, it may be helpful to maintain an object queue and add failing objects to the end of the queue in case they depend on other objects to succeed. (In some cases, it's also possible to sort objects beforehand to avoid such errors, such as by sorting parent collections before subcollections.)
- 
-When objects are created or modified locally by the user during regular usage, set ''synced = false'' to indicate that the object needs to be uploaded on the next sync. Give new objects version 0. Do not change the version when objects are modified outside of the sync process. 
  
 === ii. Get deleted data === === ii. Get deleted data ===
  
   GET <userOrGroupPrefix>/deleted?since=<version>   GET <userOrGroupPrefix>/deleted?since=<version>
 +
 +''<version>'' is, as above, the ''Last-Modified-Version'' returned from the API during the last successful sync run.
  
 Response: Response:
Line 243: Line 252:
     else:     else:
       perform conflict resolution       perform conflict resolution
 +        if user chooses deletion, delete local object, skipping delete log
              
-      if user chooses deletion, delete local object, skipping delete log +        if user chooses local modification, keep object and set synced = true and version = Last-Modified-Version
-       +
-      if user chooses local modification, keep object and set synced = true and version = ''Last-Modified-Version'+
  
 Tags removed from all items are not necessarily deleted, hence the separate tag deletion mechanism. Tags removed from all items are not necessarily deleted, hence the separate tag deletion mechanism.
Line 284: Line 292:
  
 On a ''412 Precondition Failed'' response, return to the beginning of the sync process for that library. On a ''412 Precondition Failed'' response, return to the beginning of the sync process for that library.
- 
  
 ===== Partial-Library Syncing ===== ===== Partial-Library Syncing =====
dev/web_api/v3/syncing.txt · Last modified: 2022/08/14 05:34 by dstillman