Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
dev:web_api:v3:write_requests [2021/06/02 14:15] – [Updating an Existing Item] dstillmandev:web_api:v3:write_requests [2024/10/10 02:10] (current) – Keep Zotero-Write-Token before If-Unmodified-Since-Version for now dstillman
Line 127: Line 127:
 | ''400 Bad Request'' | Invalid type/field; unparseable JSON | | ''400 Bad Request'' | Invalid type/field; unparseable JSON |
 | ''409 Conflict'' | The target library is locked. | | ''409 Conflict'' | The target library is locked. |
-| ''412 Precondition Failed'' | The provided ''Zotero-Write-Token'' has already been submitted. |+| ''412 Precondition Failed'' | The version provided in ''If-Unmodified-Since-Version'' is out of date, or the provided ''Zotero-Write-Token'' has already been submitted. |
 | ''413 Request Entity Too Large'' | Too many items submitted | | ''413 Request Entity Too Large'' | Too many items submitted |
  
Line 216: Line 216:
 === Both PUT and PATCH === === Both PUT and PATCH ===
  
-Notes and attachments can be made child items by assigning the parent item's key to the ''parentItem'' property. If parent and child items are created in the same ''POST'' request, the child items must appear after the parent item in the array of items.+Notes and attachments can be made child items by assigning the parent item's key to the ''parentItem'' property. If parent and child items are created in the same ''POST'' request, the child items must appear after the parent item in the array of items, with a locally created [[#object_keys|item key]].
  
-The item's current version number is included in the ''version'' JSON property, as well as in the ''Last-Modified-Version'' header of single-item requests. ''PUT'' and ''PATCH'' requests must include the item's current version number in either the ''version'' property or the ''If-Unmodified-Since-Version'' header. (''version'' is included in responses from the API, so clients that simply modify the editable data do not need to bother with a version header.) If the item has been changed on the server since the item was retrieved, the write request will be rejected with a ''412 Precondition Failed'' error, and the most recent version of the item will have to be retrieved from the server before changes can be made.+The item's current version number is included in the ''version'' JSON property, as well as in the ''Last-Modified-Version'' header of single-item requests. ''PUT'' and ''PATCH'' requests must include the item's current version number in either the ''version'' property or the ''If-Unmodified-Since-Version'' header. (''version'' is included in responses from the API, so clients that simply modify the editable data do not need to bother with a version header.) If the item has been changed on the server since the item was retrieved, the write request will be rejected with a ''412 Precondition Failed'' error, and the most recent version of the item will have to be retrieved from the server before changes can be made. See [[syncing#version_numbers|Version Numbers]] for more on library and object versioning.
  
 ^ Common responses ^^ ^ Common responses ^^
Line 234: Line 234:
  
   DELETE <userOrGroupPrefix>/items/<itemKey>   DELETE <userOrGroupPrefix>/items/<itemKey>
-  If-Unmodified-Since-Version: <last known item version>+  If-Unmodified-Since-Version: <last item version>
  
 ^ Common responses ^^ ^ Common responses ^^
Line 251: Line 251:
  
   204 No Content   204 No Content
-  Last-Modified-Version: <version>+  Last-Modified-Version: <library version>
  
  
Line 266: Line 266:
   POST <userOrGroupPrefix>/collections   POST <userOrGroupPrefix>/collections
   Content-Type: application/json   Content-Type: application/json
-  Zotero-Write-Token: <write token>+  Zotero-Write-Token: <write token> or If-Unmodified-Since-Version: <last library version>
  
 <code>[ <code>[
Line 278: Line 278:
 | ''200 OK'' | The request completed without a general error. See the response JSON for status of individual writes. | | ''200 OK'' | The request completed without a general error. See the response JSON for status of individual writes. |
 | ''409 Conflict'' | The target library is locked. | | ''409 Conflict'' | The target library is locked. |
-| ''412 Precondition Failed'' | The provided Zotero-Write-Token has already been submitted. |+| ''412 Precondition Failed'' | The version provided in ''If-Unmodified-Since-Version'' is out of date, or the provided ''Zotero-Write-Token'' has already been submitted. |
  
 ==== Updating an Existing Collection ==== ==== Updating an Existing Collection ====
Line 308: Line 308:
  
   DELETE <userOrGroupPrefix>/collections/<collectionKey>   DELETE <userOrGroupPrefix>/collections/<collectionKey>
-  If-Unmodified-Since-Version: <last-retrieved-version>+  If-Unmodified-Since-Version: <last collection version>
  
 ^ Common responses ^^ ^ Common responses ^^
Line 321: Line 321:
  
   DELETE <userOrGroupPrefix>/collections?collectionKey=<collectionKey>,<collectionKey>,<collectionKey>   DELETE <userOrGroupPrefix>/collections?collectionKey=<collectionKey>,<collectionKey>,<collectionKey>
-  If-Unmodified-Since-Version: <version>+  If-Unmodified-Since-Version: <last library version>
  
   204 No Content   204 No Content
-  Last-Modified-Version: <version>+  Last-Modified-Version: <library version>
  
  
Line 339: Line 339:
   POST <userOrGroupPrefix>/searches   POST <userOrGroupPrefix>/searches
   Content-Type: application/json   Content-Type: application/json
-  Zotero-Write-Token: <write token>+  Zotero-Write-Token: <write token> or If-Unmodified-Since-Version: <last library version>
  
 <code>[ <code>[
Line 362: Line 362:
 | ''200 OK'' | The request completed without a general error. See the response JSON for status of individual writes. | | ''200 OK'' | The request completed without a general error. See the response JSON for status of individual writes. |
 | ''409 Conflict'' | The target library is locked. | | ''409 Conflict'' | The target library is locked. |
-| ''412 Precondition Failed'' | The provided Zotero-Write-Token has already been submitted. |+| ''412 Precondition Failed'' | The version provided in ''If-Unmodified-Since-Version'' is out of date, or the provided ''Zotero-Write-Token'' has already been submitted. |
  
 ==== Deleting Multiple Searches ==== ==== Deleting Multiple Searches ====
Line 369: Line 369:
  
   DELETE <userOrGroupPrefix>/searches?searchKey=<searchKey>,<searchKey>,<searchKey>   DELETE <userOrGroupPrefix>/searches?searchKey=<searchKey>,<searchKey>,<searchKey>
-  If-Unmodified-Since-Version: <version>+  If-Unmodified-Since-Version: <last library version>
  
   204 No Content   204 No Content
-  Last-Modified-Version: <version>+  Last-Modified-Version: <library version>
  
 ^ Common responses ^^ ^ Common responses ^^
Line 387: Line 387:
  
   DELETE <userOrGroupPrefix>/tags?tag=<URL-encoded tag 1> || <URL-encoded tag 2> || <URL-encoded tag 3>   DELETE <userOrGroupPrefix>/tags?tag=<URL-encoded tag 1> || <URL-encoded tag 2> || <URL-encoded tag 3>
-  If-Unmodified-Since-Version: <version>+  If-Unmodified-Since-Version: <last library version>
  
   204 No Content   204 No Content
-  Last-Modified-Version: <version>+  Last-Modified-Version: <library version>
  
  
Line 401: Line 401:
   POST <userOrGroupPrefix>/collections   POST <userOrGroupPrefix>/collections
   Content-Type: application/json   Content-Type: application/json
 +  Zotero-Write-Token: <write token> or If-Unmodified-Since-Version: <last library version>
  
 <code>[ <code>[
Line 412: Line 413:
 ]</code> ]</code>
  
-For syncing objects with predetermined keys, an object key can also be provided with new objects. See the [[Syncing]] documentation for more information.+For [[syncing]] objects with predetermined keys, an [[#object_keys|object key]] can also be provided with new objects.
  
 ''200'' response: ''200'' response:
  
   Content-Type: application/json   Content-Type: application/json
-  Last-Modified-Version: <version>+  Last-Modified-Version: <library version>
  
 <code>{ <code>{
Line 478: Line 479:
  
 Note that ''POST'' follows ''PATCH'' semantics, meaning that any properties not specified will be left untouched on the server. To erase an existing property, include it with an empty string or ''false'' as the value. Note that ''POST'' follows ''PATCH'' semantics, meaning that any properties not specified will be left untouched on the server. To erase an existing property, include it with an empty string or ''false'' as the value.
 +
 +===== Object Keys =====
 +
 +While the server will automatically generate valid keys for uploaded objects, in some situations, such as when [[syncing]] or creating a parent and child item in the same request, it may be desirable or necessary to create object keys locally.
 +
 +Local object keys should conform to the pattern ''/[23456789ABCDEFGHIJKLMNPQRSTUVWXYZ]{8}/''.
  
 ===== Zotero-Write-Token ===== ===== Zotero-Write-Token =====
Line 485: Line 492:
 ''Zotero-Write-Token'' is an optional HTTP header, containing a client-generated random 32-character identifier string, that can be included with unversioned write requests to prevent them from being processed more than once (e.g., if a user clicks a form submit button twice). The Zotero server caches write tokens for successful requests for 12 hours, and subsequent requests from the same API key using the same write token will be rejected with a ''412 Precondition Failed'' status code. If a request fails, the write token will not be stored. ''Zotero-Write-Token'' is an optional HTTP header, containing a client-generated random 32-character identifier string, that can be included with unversioned write requests to prevent them from being processed more than once (e.g., if a user clicks a form submit button twice). The Zotero server caches write tokens for successful requests for 12 hours, and subsequent requests from the same API key using the same write token will be rejected with a ''412 Precondition Failed'' status code. If a request fails, the write token will not be stored.
  
-If using versioned write requests (i.e., those that include an ''If-Unmodified-Since-Version'' HTTP header or individual object ''version'' properties), ''Zotero-Write-Token'' is redundant and should be omitted.+If using [[syncing#version_numbers|versioned write requests]] (i.e., those that include an ''If-Unmodified-Since-Version'' HTTP header or individual object ''version'' properties), ''Zotero-Write-Token'' is redundant and should be omitted.
  
 ===== Examples ===== ===== Examples =====
  
 See the [[Syncing]] page for an example workflow that puts together read and write methods for complete and efficient syncing of Zotero data via the API. See the [[Syncing]] page for an example workflow that puts together read and write methods for complete and efficient syncing of Zotero data via the API.
dev/web_api/v3/write_requests.1622657750.txt.gz · Last modified: 2021/06/02 14:15 by dstillman