| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| dev:web_api:v2:syncing [2013/02/09 16:41] – dstillman | dev:web_api:v2:syncing [2017/11/27 04:18] (current) – Remove Zotero 5 warning bwiernik |
|---|
| ====== API-Based Syncing ====== | ====== API-Based Syncing ====== |
| |
| <html><p style="color:red"><strong>This is a draft document. Much of the functionality mentioned is not currently available in the public API.</strong></p></html> | **This is version 2 of the Zotero Web API. For new development, use [[:dev/web_api/v3/start|API version 3]].** |
| |
| This document outlines the recommended steps for synchronizing a Zotero API client with the Zotero server. | This document outlines the recommended steps for synchronizing a Zotero API client with the Zotero server. |
| TODO: | TODO: |
| |
| * Backoff instruction | * Full-text content ([[dev:web_api/v2/fulltext_content|see separate documentation]]) |
| * WebSocket notifications | * Backoff instruction ([[dev:web_api/v2/read_requests#rate_limiting|see read request documentation]]) |
| | * WebSocket notifications (planned feature) |
| ===== Sync Properties ===== | ===== Sync Properties ===== |
| |
| === If-Modified-Since-Version === | === If-Modified-Since-Version === |
| |
| The ''If-Modified-Since-Version'' request header can be used to efficiently check for new data. If ''If-Modified-Since-Version'' is passed with a multi-object read request and data has not changed in the library, the API will return ''304 Not Modified''. If ''If-Modified-Since-Version'' is passed with a single-object read request, a ''304 Not Modified'' will be returned if the individual object has not changed. | The ''If-Modified-Since-Version'' request header can be used to efficiently check for new data. If ''If-Modified-Since-Version: <libraryVersion>'' is passed with a multi-object read request and data has not changed in the library since the specified version, the API will return ''304 Not Modified''. If ''If-Modified-Since-Version: <objectVersion>'' is passed with a single-object read request, a ''304 Not Modified'' will be returned if the individual object has not changed. |
| |
| === If-Unmodified-Since-Version === | === If-Unmodified-Since-Version === |
| |
| The ''If-Unmodified-Since-Version'' request header is used to ensure that existing data won't be overwritten by a client with out-of-date data. All write requests that modify existing objects must include either the ''If-Unmodified-Since-Version'' header or a [[#JSON version property]] for each object. | The ''If-Unmodified-Since-Version'' request header is used to ensure that existing data won't be overwritten by a client with out-of-date data. All write requests that modify existing objects must include either the ''If-Unmodified-Since-Version: <version>'' header or a [[#JSON version property]] for each object. If both are omitted, the API will return a ''428 Precondition Required''. |
| |
| For write requests to multi-object endpoints such as ''<userOrGroupPrefix>/items'', the API will return ''412 Precondition Failed'' if the library has been modified since the passed version. For write requests to single-object endpoints such as ''<userOrGroupPrefix>/items/<itemKey>'', the API will return a ''412'' if the object has been modified since the passed version. | For write requests to multi-object endpoints such as ''<userOrGroupPrefix>/items'', the API will return ''412 Precondition Failed'' if the library has been modified since the passed version. For write requests to single-object endpoints such as ''<userOrGroupPrefix>/items/<itemKey>'', the API will return a ''412'' if the object has been modified since the passed version. |
| |
| ''If-Unmodified-Since-Version'' also enables more efficient uploads. Rather than first polling for remote updates, clients that have changes to upload should start by trying to perform the necessary [[#iv_upload_modified_data|write requests]], passing the current local library version in the ''If-Unmodified-Since-Version'' header. If updated data is available, the API will return ''412 Precondition Failed'', indicating that the client must first retrieve the updated data. In the absence of a ''412'' for a write request, clients with local modifications do not need to check for remote changes explicitly. | Clients should generally use ''If-Unmodified-Since-Version'' for multi-object requests only if they have downloaded all server data for the object type being written. Otherwise, a client creating a new object could assign an object key that already exists on the server and accidentally overwrite the existing object. |
| |
| ''If-Unmodified-Since-Version'' replaces the ''If-Match: <etag>'' header previously required for single-object writes. | ''If-Unmodified-Since-Version'' also enables more efficient syncs. Rather than first polling for remote updates, clients that have changes to upload should start by trying to perform the necessary [[#iv_upload_modified_data|write requests]], passing the current local library version in the ''If-Unmodified-Since-Version'' header. If updated data is available, the API will return ''412 Precondition Failed'', indicating that the client must first retrieve the updated data. In the absence of a ''412'' for a write request, clients with local modifications do not need to check for remote changes explicitly. |
| | |
| | ''If-Unmodified-Since-Version: <version>'' replaces the ''If-Match: <etag>'' header previously required for single-object writes. |
| |
| === JSON version property === | === JSON version property === |
| ''content=json'' responses will include a ''collectionVersion'', ''itemVersion'', or ''searchVersion'' property in each object's JSON indicating the current version of that object. This value will be identical to the value given in the Atom entry's ''zapi:version'' element. For single-object requests, this will also be identical to the value of ''Last-Modified-Version''. | ''content=json'' responses will include a ''collectionVersion'', ''itemVersion'', or ''searchVersion'' property in each object's JSON indicating the current version of that object. This value will be identical to the value given in the Atom entry's ''zapi:version'' element. For single-object requests, this will also be identical to the value of ''Last-Modified-Version''. |
| |
| If included in JSON submitted back to the API, the JSON version property will behave equivalently to a single-object ''If-Unmodified-Since-Version'': if the object has been modified since the specified version, the API will return a ''412 Precondition Failed''. Write requests that do not include ''If-Unmodified-Since-Version'' must include the JSON version property with each object. | If included in JSON submitted back to the API, the JSON version property will behave equivalently to a single-object ''If-Unmodified-Since-Version'': if the object has been modified since the specified version, the API will return a ''412 Precondition Failed''. When writing objects that include objects keys, either the request must include ''If-Unmodified-Since-Version'' or each object must include the JSON version property. When writing new objects with an object key in a request without ''If-Unmodified-Since-Version'', use the special version 0 to indicate that the objects should not yet exist on the server. |
| |
| While ''If-Unmodified-Since-Version'' and the JSON version property are not mutually exclusive for write requests, they are redundant, and generally clients should use one or the other depending on their interaction mechanism. See [[#Partial-Library Syncing]] for a discussion of possible syncing methods. | While ''If-Unmodified-Since-Version'' and the JSON version property are not mutually exclusive for write requests, they are redundant, and generally clients should use one or the other depending on their interaction mechanism. See [[#Partial-Library Syncing]] for a discussion of possible syncing methods. |
| |
| <code javascript>[ | <code javascript>[ |
| "<objectKey>": "<version>", | "<objectKey>": <version>, |
| "<objectKey>": "<version>" | "<objectKey>": <version> |
| "<objectKey>": "<version>", | "<objectKey>": <version>, |
| ]</code> | ]</code> |
| |
| === iv. Upload modified data === | === iv. Upload modified data === |
| |
| Upload objects with ''synced'' set to ''false''. Follow the instructions in [[write_requests#creating_multiple_objects|Creating Multiple Objects]], but add a ''collectionKey'', ''searchKey'', or ''itemKey'' property to each object. Pass the current library version as ''If-Unmodified-Since-Version'', replacing ''Zotero-Write-Token''. | Upload objects which have ''synced'' set to ''false''. Follow the instructions in [[write_requests#updating_multiple_objects|Updating Multiple Objects]], passing the current library version as ''If-Unmodified-Since-Version''. |
| | |
| Items can also include ''dateAdded'' and ''dateModified'' properties containing UTC timestamps in SQL DATETIME format (e.g., "2012-10-03 16:42:12"). ''dateAdded'' should be specified only on new items; passing a different ''dateAdded'' in an update will result in a ''409'' (?) error. | |
| |
| Creators, tags, and relations are included in item objects and are not synced separately. | Creators, tags, and relations are included in item objects and are not synced separately. |
| |
| POST <userOrGroupPrefix>/collections | |
| Content-Type: application/json | |
| If-Unmodified-Since-Version: <version> | |
| |
| <code javascript>{ | |
| "collections": [ | |
| { | |
| "collectionKey": "BD85JEM4", | |
| "name": "My Collection", | |
| "parentCollection": false | |
| }, | |
| { | |
| "collectionKey": "MNC5SAPD", | |
| "name": "My Subcollection", | |
| "parentCollection": "BD85JEM4" | |
| } | |
| ] | |
| }</code> | |
| |
| 200 response: | |
| |
| Content-Type: application/json | |
| Last-Modified-Version: <version> | |
| |
| <code javascript>{ | |
| "success": { | |
| "0": "<objectKey>", | |
| "2": "<objectKey>" | |
| }, | |
| "unchanged": { | |
| "4": "<objectKey>" | |
| }, | |
| "failed": { | |
| "1": { | |
| "key": "<objectKey>", | |
| "code": <HTTP response code>, | |
| "message": "<error message>" | |
| }, | |
| "3": { | |
| "key": "<objectKey>", | |
| "code": <HTTP response code>, | |
| "message": "<error message>" | |
| }, | |
| } | |
| }</code> | |
| |
| The keys of the ''success'', ''unchanged'', and ''failed'' objects are the numeric indexes of the Zotero objects in the uploaded array. The ''Last-Modified-Version'' is the version that has been assigned to Zotero objects in the ''success'' object. | |
| |
| On a ''200'' response, set ''synced = true'' and ''version = Last-Modified-Version'' for each successfully uploaded Zotero object and store ''Last-Modified-Version'' as the current library version to be passed with the next write request. Do not update the version of Zotero objects in the ''unchanged'' object. Retry non-fatal failures. | On a ''200'' response, set ''synced = true'' and ''version = Last-Modified-Version'' for each successfully uploaded Zotero object and store ''Last-Modified-Version'' as the current library version to be passed with the next write request. Do not update the version of Zotero objects in the ''unchanged'' object. Retry non-fatal failures. |
Upgrade Storage