| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| dev:web_api:v2:syncing [2013/03/05 02:13] – [JSON version property] dstillman | dev:web_api:v2:syncing [2017/11/27 04:18] (current) – Remove Zotero 5 warning bwiernik |
|---|
| ====== API-Based Syncing ====== | ====== API-Based Syncing ====== |
| |
| **This is not currently the default [[read_requests#api_versioning|version]] of the Zotero API. Include the HTTP header ''Zotero-API-Version: 2'' to access this version.** | **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: |
| |
| * Full-text content | * Full-text content ([[dev:web_api/v2/fulltext_content|see separate documentation]]) |
| * Backoff instruction | * Backoff instruction ([[dev:web_api/v2/read_requests#rate_limiting|see read request documentation]]) |
| * WebSocket notifications | * WebSocket notifications (planned feature) |
| ===== Sync Properties ===== | ===== Sync Properties ===== |
| |
| 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'' 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. | ''If-Unmodified-Since-Version: <version>'' replaces the ''If-Match: <etag>'' header previously required for single-object writes. |
| |
| <code javascript>[ | <code javascript>[ |
| "<objectKey>": "<version>", | "<objectKey>": <version>, |
| "<objectKey>": "<version>" | "<objectKey>": <version> |
| "<objectKey>": "<version>", | "<objectKey>": <version>, |
| ]</code> | ]</code> |
| |
Upgrade Storage