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:v2:write_requests [2013/02/09 23:42] – [Both PUT and PATCH] dstillmandev:web_api:v2:write_requests [2017/11/27 04:17] (current) – Remove Zotero 5 warning bwiernik
Line 1: Line 1:
 ====== Zotero Server Write Requests ====== ====== Zotero Server Write Requests ======
  
-This page documents the write methods of the [[start|Zotero Server API]]. See the [[Read Requests]] page for basic information on accessing the API, including possible HTTP status codes not listed here.+**This is version 2 of the Zotero Web API. For new development, use [[:dev/web_api/v3/start|API version 3]].** 
 + 
 +This page documents the write methods of the [[start|Zotero Web API]]. See the [[Read Requests]] page for basic information on accessing the API, including possible HTTP status codes not listed here.
  
 An API key with write access to a given library is necessary to use write methods. An API key with write access to a given library is necessary to use write methods.
Line 203: Line 205:
  
 See [[#creating_multiple_objects|Creating Multiple Objects]] for more information on the response format. See [[#creating_multiple_objects|Creating Multiple Objects]] for more information on the response format.
 +
 ==== Creating Multiple Items ==== ==== Creating Multiple Items ====
  
 See [[#creating_multiple_objects|Creating Multiple Objects]]. See [[#creating_multiple_objects|Creating Multiple Objects]].
 +
 ==== Updating an Existing Item ==== ==== Updating an Existing Item ====
  
Line 287: Line 291:
 ==== Updating Multiple Items ==== ==== Updating Multiple Items ====
  
-See the [[#updating_multiple_objects|Updating Multiple Objects]].+See [[#updating_multiple_objects|Updating Multiple Objects]]. 
 ==== Deleting an Item ==== ==== Deleting an Item ====
  
Line 312: Line 317:
   204 No Content   204 No Content
   Last-Modified-Version: <version>   Last-Modified-Version: <version>
 +
 +
 +^ Common responses ^^
 +| ''204 No Content'' | The items were deleted. |
 +| ''409 Conflict'' | The target library is locked. |
 +| ''412 Precondition Failed'' | The library has changed since the specified version. |
  
 ===== Collection Requests ===== ===== Collection Requests =====
Line 379: Line 390:
   204 No Content   204 No Content
   Last-Modified-Version: <version>   Last-Modified-Version: <version>
 +
 +
 +^ Common responses ^^
 +| ''204 No Content'' | The collections were deleted. |
 +| ''409 Conflict'' | The target library is locked. |
 +| ''412 Precondition Failed'' | The library has changed since the specified version. |
  
  
Line 423: Line 440:
   204 No Content   204 No Content
   Last-Modified-Version: <version>   Last-Modified-Version: <version>
 +
 +^ Common responses ^^
 +| ''204 No Content'' | The searches were deleted. |
 +| ''409 Conflict'' | The target library is locked. |
 +| ''412 Precondition Failed'' | The library has changed since the specified version. |
 +
 +
  
  
Line 442: Line 466:
 ==== Creating Multiple Objects ==== ==== Creating Multiple Objects ====
  
-Multiple collections, saved searches, and items can be created in the same requests by including multiple objects in the ''collections'', ''searches'', and ''items'' properties:+Up to 50 collections, saved searches, or items can be created in a single request by including multiple objects in the ''collections'', ''searches'', or ''items'' property:
  
   POST <userOrGroupPrefix>/collections   POST <userOrGroupPrefix>/collections
Line 459: Line 483:
   ]   ]
 }</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.
  
 200 response: 200 response:
Line 496: Line 522:
  
 === Updating Multiple Objects === === Updating Multiple Objects ===
 +
 +Up to 50 collections, saved searches, or items can be updated in a single request.
  
 Follow the instructions in [[#creating_multiple_objects|Creating Multiple Objects]], but add an ''itemKey'', ''collectionKey'', or ''searchKey'' property to each object. Pass the current library version as ''If-Unmodified-Since-Version'', replacing ''Zotero-Write-Token'', or include an ''itemVersion'', ''collectionVersion'', or ''searchVersion'' in each object. Follow the instructions in [[#creating_multiple_objects|Creating Multiple Objects]], but add an ''itemKey'', ''collectionKey'', or ''searchKey'' property to each object. Pass the current library version as ''If-Unmodified-Since-Version'', replacing ''Zotero-Write-Token'', or include an ''itemVersion'', ''collectionVersion'', or ''searchVersion'' in each object.
  
-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.+Items can also include ''dateAdded'' and ''dateModified'' properties containing UTC timestamps in SQL DATETIME format (e.g., "2012-10-03 16:42:12"). If ''dateAdded'' is included with an existing item, it must match the existing ''dateAdded'' value or else the API will return a 400 error. If a new ''dateModified'' time is not included with an update to existing item, the item's ''dateModified'' value will be set to the current time.
  
 Creators, tags, and relations are included in item objects and cannot be modified separately. Creators, tags, and relations are included in item objects and cannot be modified separately.
Line 522: Line 550:
 }</code> }</code>
  
-200 response: +The response is the same as that in [[#creating_multiple_objects|Creating Multiple Objects]].
- +
-  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.+
  
 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.
dev/web_api/v2/write_requests.1360471346.txt.gz · Last modified: 2013/02/09 23:42 by dstillman