====== Zotero Web API Write Requests ======
This page documents the write methods of the [[start|Zotero Web API]]. See the [[Basics]] page for basic information on accessing the API, including possible HTTP status codes not listed here.
An [[basics#authentication|API key]] with write access to a given library is necessary to use write methods.
===== JSON Object Data =====
By default, objects returned from the API in ''format=json'' mode include a ''data'' property containing "editable JSON" — that is, all the object fields that can be modified and sent back to the server:
{
"key": "ABCD2345",
"version": 1,
"library": { ... },
"links": { ... },
"meta": { ... },
"data": {
"key": "ABCD2345",
"version": 1,
"itemType": "webpage",
"title": "Zotero Quick Start Guide",
"creators": [
{
"creatorType": "author",
"name": "Center for History and New Media"
}
],
"abstractNote": "",
"websiteTitle": "Zotero",
"websiteType": "",
"date": "",
"shortTitle": "",
"url": "https://www.zotero.org/support/quick_start_guide",
"accessDate": "2014-06-12T21:28:55Z",
"language": "",
"rights": "",
"extra": "",
"dateAdded": "2014-06-12T21:28:55Z",
"dateModified": "2014-06-12T21:28:55Z",
"tags": [],
"collections": [],
"relations": {}
}
}
There are two ways to make changes to the provided JSON:
==== Programmatic Approach ====
For programmatic access to the API, the recommended approach is to extract the editable JSON from the ''data'' property, make changes as necesssary, and upload just the editable JSON back to the API. For new items, an [[types_and_fields#getting_a_template_for_a_new_item|empty template]] of the editable JSON can be retrieved from the API.
This approach reduces upload bandwidth by sending only the data that is actually processed by the server. (For an even more efficient upload, the HTTP ''PATCH'' method, discussed below, can be used to send only the fields that have changed.) The examples in this documentation assume programmatic access.
==== REST Approach ====
For more casual access, the API supports standard REST behavior, allowing the entire downloaded JSON to be reuploaded. This allows edits to be performed without writing a single line of code:
$ URL="https://api.zotero.org/users/1234567/items"
$ API_KEY="P9NiFoyLeZu2bZNvvuQPDWsd"
$ curl -H "Zotero-API-Key: $API_KEY" $URL > items.json
$ vi items.json # edit the item data
$ curl -H "Zotero-API-Key: $API_KEY" -d @items.json -v $URL
In this example, a JSON array of items is being saved to a text file, modified in a text editor, and then POSTed back to the same URL.
This approach allows a complicated task such as batch editing to be performed using only cURL and a text editor. Any objects modified in the text file will be updated on the server, while unmodified objects will be left unchanged.
A similar process can be used with PUT for individual objects:
$ URL="https://api.zotero.org/users/1234567/items/ABCD2345"
$ API_KEY="P9NiFoyLeZu2bZNvvuQPDWsd"
$ curl -H "Zotero-API-Key: $API_KEY" $URL > item.json
$ vi items.json # edit the item data
$ curl -H "Zotero-API-Key: $API_KEY" -X PUT -d @item.json -v $URL
Note that when uploading full JSON, only the ''data'' property is processed. All other properties (''library'', ''links'', ''meta'', etc.) are ignored.
===== Item Requests =====
==== Creating an Item ====
When creating a new item, first get empty JSON for the item type with an [[types_and_fields#getting_a_template_for_a_new_item|item template request]] (or use a cached version of the template). Then modify it and resubmit it to the server in an array:
POST /items
Content-Type: application/json
Zotero-Write-Token: or If-Unmodified-Since-Version:
[
{
"itemType" : "book",
"title" : "My Book",
"creators" : [
{
"creatorType":"author",
"firstName" : "Sam",
"lastName" : "McAuthor"
},
{
"creatorType":"editor",
"name" : "John T. Singlefield"
}
],
"tags" : [
{ "tag" : "awesome" },
{ "tag" : "rad", "type" : 1 }
],
"collections" : [
"BCDE3456", "CDEF4567"
],
"relations" : {
"owl:sameAs" : "http://zotero.org/groups/1/items/JKLM6543",
"dc:relation" : "http://zotero.org/groups/1/items/PQRS6789",
"dc:replaces" : "http://zotero.org/users/1/items/BCDE5432"
}
}
]
All properties other than ''itemType'', ''tags'', ''collections'', and ''relations'' are optional.
^ Common responses ^^
| ''200 OK'' | The request completed. See the response JSON for status of individual writes. |
| ''400 Bad Request'' | Invalid type/field; unparseable JSON |
| ''409 Conflict'' | The target library is locked. |
| ''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 |
''200 OK'' response:
{
"success": {
"0": ""
},
"unchanged": {},
"failed": {},
}
}
See [[#creating_multiple_objects|Creating Multiple Objects]] for more information on the response format.
==== Creating Multiple Items ====
See [[#creating_multiple_objects|Creating Multiple Objects]].
==== Updating an Existing Item ====
To update an existing item, first retrieve the current version of the item:
GET /items/
The editable data, similar to the item data shown above in [[#creating_an_item|Creating an Item]], will be found in the ''data'' property in the response.
The API supports two ways of modifying item data: by uploading full item data (''PUT'') or by sending just the data that changed (''PATCH'').
=== Full-item updating (PUT) ===
With ''PUT'', you submit the item's complete editable JSON to the server, typically by modifying the downloaded editable JSON --- that is, the contents of the ''data'' property --- directly and resubmitting it:
PUT /items/
Content-Type: application/json
{
"key": "ABCD2345",
"version": 1,
"itemType" : "book",
"title" : "My Amazing Book",
"creators" : [
{
"creatorType":"author",
"firstName" : "Sam",
"lastName" : "McAuthor"
},
{
"creatorType":"editor",
"name" : "Jenny L. Singlefield"
}
],
"tags" : [
{ "tag" : "awesome" },
{ "tag" : "rad", "type" : 1 }
],
"collections" : [
"BCDE3456", "CDEF4567"
],
"relations" : {
"owl:sameAs" : "http://zotero.org/groups/1/items/JKLM6543",
"dc:relation" : "http://zotero.org/groups/1/items/PQRS6789",
"dc:replaces" : "http://zotero.org/users/1/items/BCDE5432"
}
}
All properties other than ''itemType'', ''tags'', ''collections'', and ''relations'' are optional. Any existing fields not specified will be removed from the item. If ''creators'', ''tags'', ''collections'', or ''relations'' are empty, any associated creators/tags/collections/relations will be removed from the item.
=== Partial-item updating (PATCH) ===
With ''PATCH'', you can submit just the properties that have actually changed, for a potentially much more efficient operation. Properties not included in the uploaded JSON are left untouched on the server. To clear a property, pass an empty string or an empty array as appropriate.
PATCH /items/
If-Unmodified-Since-Version:
{
"date" : "2013"
"collections" : [
"BCDE3456", "CDEF4567"
]
}
This would add a ''date'' field to the item and add it in the two specified collections if not already present. Array properties are interpreted as complete lists, so omitting a collection key would cause the item to be removed from that collection.
The ''PATCH'' behavior is also available when [[write_requests#updating_multiple_objects|modifying multiple items]] via ''POST''.
=== 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, 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. See [[syncing#version_numbers|Version Numbers]] for more on library and object versioning.
^ Common responses ^^
| ''204 No Content'' | The item was successfully updated. |
| ''400 Bad Request'' | Invalid type/field; unparseable JSON |
| ''409 Conflict'' | The target library is locked. |
| ''412 Precondition Failed'' | The item has changed since retrieval (i.e., the provided item version no longer matches). |
==== Updating Multiple Items ====
See [[#updating_multiple_objects|Updating Multiple Objects]].
==== Deleting an Item ====
DELETE /items/
If-Unmodified-Since-Version:
^ Common responses ^^
| ''204 No Content'' | The item was deleted. |
| ''409 Conflict'' | The target library is locked. |
| ''412 Precondition Failed'' | The item has changed since retrieval (i.e., the provided item version no longer matches). |
| ''428 Precondition Required'' | ''If-Unmodified-Since-Version'' was not provided. |
==== Deleting Multiple Items ====
Up to 50 items can be deleted in a single request.
DELETE /items?itemKey=,,
If-Unmodified-Since-Version:
204 No Content
Last-Modified-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. |
| ''428 Precondition Required'' | ''If-Unmodified-Since-Version'' was not provided. |
===== Collection Requests =====
==== Creating a Collection ====
POST /collections
Content-Type: application/json
Zotero-Write-Token: or If-Unmodified-Since-Version:
[
{
"name" : "My Collection",
"parentCollection" : "QRST9876"
}
]
^ Common responses ^^
| ''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. |
| ''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 ====
GET /collections/
Editable JSON will be found in the ''data'' property.
PUT /collections/
Content-Type: application/json
{
"key" : "DM2F65CA",
"version" : 156,
"name" : "My Collection",
"parentCollection" : false
}
^ Common responses ^^
| ''200 OK'' | The collection was updated. |
| ''409 Conflict'' | The target library is locked. |
| ''412 Precondition Failed'' | The collection has changed since retrieval (i.e., the provided collection version no longer matches). |
==== Collection-Item Membership ====
Items can be added to or removed from collections via the ''collections'' property in the item JSON.
==== Deleting a Collection ====
DELETE /collections/
If-Unmodified-Since-Version:
^ Common responses ^^
| ''204 No Content'' | The collection was deleted. |
| ''409 Conflict'' | The target library is locked. |
| ''412 Precondition Failed'' | The collection has changed since retrieval (i.e., the provided ETag no longer matches). |
==== Deleting Multiple Collections ====
Up to 50 collections can be deleted in a single request.
DELETE /collections?collectionKey=,,
If-Unmodified-Since-Version:
204 No Content
Last-Modified-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. |
===== Saved Search Requests =====
==== Creating a Search ====
POST /searches
Content-Type: application/json
Zotero-Write-Token: or If-Unmodified-Since-Version:
[
{
"name": "My Search",
"conditions": [
{
"condition": "title",
"operator": "contains",
"value": "foo"
},
{
"condition": "date",
"operator": "isInTheLast",
"value": "7 days"
}
]
}
]
^ Common responses ^^
| ''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. |
| ''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 ====
Up to 50 searches can be deleted in a single request.
DELETE /searches?searchKey=,,
If-Unmodified-Since-Version:
204 No Content
Last-Modified-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. |
===== Tag Requests =====
==== Deleting Multiple Tags ====
Up to 50 tags can be deleted in a single request.
DELETE /tags?tag= || ||
If-Unmodified-Since-Version:
204 No Content
Last-Modified-Version:
===== Multi-Object Requests =====
==== Creating Multiple Objects ====
Up to 50 collections, saved searches, or items can be created in a single request by including multiple objects in an array:
POST /collections
Content-Type: application/json
Zotero-Write-Token: or If-Unmodified-Since-Version:
[
{
"name" : "My Collection",
"parentCollection": "QRST9876"
},
{
"name": "My Other Collection"
}
]
For [[syncing]] objects with predetermined keys, an [[#object_keys|object key]] can also be provided with new objects.
''200'' response:
Content-Type: application/json
Last-Modified-Version:
{
"successful": {
"0": "",
"2": ""
},
"unchanged": {
"4": ""
}
"failed": {
"1": {
"key": "",
"code": ,
"message": ""
},
"3": {
"key": "",
"code": ,
"message": ""
},
}
}
The keys of the ''successful'', ''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 any Zotero objects in the ''successful'' object --- that is, objects that were modified in this request.
^ Common responses ^^
| ''200 OK'' | The objects were uploaded. |
| ''409 Conflict'' | The target library is locked. |
| ''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 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 include a ''key'' and ''version'' property in each object. If modifying editable JSON returned from the API, these properties will already exist and shouldn't be modified. As an alternative to individual ''version'' properties, the last-known library version can be passed via the ''If-Unmodified-Since-Version'' HTTP Header.
Items can also include ''dateAdded'' and ''dateModified'' properties containing timestamps in [[http://en.wikipedia.org/wiki/ISO_8601|ISO 8601 format]] (e.g., "2014-06-10T13:52:43Z"). 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. Editable JSON returned from the API includes ''dateAdded'' and ''dateModified'' in the correct format, so clients that are content with server-set modification times can simply ignore these properties.
POST /collections
Content-Type: application/json
[
{
"key": "BD85JEM4",
"version": 414,
"name": "My Collection",
"parentCollection": false
},
{
"key": "MNC5SAPD",
"version": 416
"name": "My Subcollection",
"parentCollection": "BD85JEM4"
}
]
The response is the same as that in [[#creating_multiple_objects|Creating Multiple Objects]].
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: 19a4f01ad623aa7214f82347e3711f56
''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 [[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 =====
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.Among the most interesting of Plutarch’s religious writings is one entitled On the Delays in the Divine Vengeance. As might be expected from the name, it deals with a problem closely akin to that which ages before had been made the subject of such sublime imagery and such inconclusive reasoning by the author of the Book of Job. What troubled the Hebrew poet was the apparently undeserved suffering of the just. What the Greek moralist feels himself called on to explain is the apparent prosperity and impunity of the wicked. He will not for a moment admit that crime remains unavengeful; his object is to show why the retribution does not follow directly on the deed. And, in order to account for this, he adduces a number of very ingenious reasons. By acting deliberately rather than in blind anger, the gods wish to read us a useful lesson in patience and forbearance. Sometimes their object is to give the sinner an opportunity for repentance and amendment; or else they may be holding him in reserve for the performance of some beneficial work. At other times, their justice is delayed only that it may be manifested by some signal and striking form of retribution. In many cases, the final stroke has been preceded by long years of secret torment; and even where no suffering seems to be inflicted, the pangs of remorse may furnish a sufficient expiation. Or again, vengeance may be reserved for a future generation. Some persons hold that to267 visit the sins of the fathers on the children is unjust, but in this they are profoundly mistaken. Members of the same family and citizens of the same state are connected as parts of one organic whole; sharing in the benefits which accrue from the good deeds of their predecessors, it is right that they should also share in the responsibility for their crimes. Moreover, the posterity of the wicked inherit a sinful disposition which, as the gods can clearly foresee, would betray itself in overt acts were they not cut off in their youth. And it is equally an error to suppose that the original wrongdoers remain unaffected by the retribution which befalls their descendants. On the contrary, they witness it from the next world, where it adds poignancy to their remorse, and entails on them fresh penalties over and above those which they have already been doomed to suffer. This preference of pure abstract speculation to beneficent290 action may be traced to the influence of Aristotle. Some of the most enthusiastic expressions used by Plotinus in speaking of his supreme principle seem to have been suggested by the Metaphysics and the last book of the Nicomachean Ethics. The self-thinking thought of the Stagirite does not, indeed, take the highest rank with him. But it is retained in his system, and is only relegated to a secondary place because, for reasons which we shall explain hereafter, it does not fulfil equally well with Plato’s Idea of Good, the condition of absolute and indivisible unity, without which a first principle could not be conceived by any Greek philosopher. But this apparent return to the standpoint of the Republic really involves a still wider departure from its animating spirit. In other words, Plotinus differs from Aristotle as Aristotle himself had differed from Plato; he shares the same speculative tendency, and carries it to a greater extreme. "Yes?" she answered, and stroked the head of the fawn. She dropped beside him and tried to hold him down. "He did not know I was coming here," she pleaded. "It was a mistake, Jack! Will you wait until I tell you? Will you wait?" She was clinging around his neck and would not be shaken off. He dragged her in the dust, trying to get free himself. Feeling entirely at ease, he climbed into the car, with a copy of the Cincinnati Gazette, which he had bought of a newsboy, lighted his pipe, put on his spectacles, and settled down to a labored, but thorough perusal of the paper, beginning at the head-lines on the upper left-hand corner, and taking in every word, advertisements and all, as systematically as he would weed a garden-bed or milk a cow. The Deacon never did anything slip-shod, especially when he had to pay 10 cents for a copy of the Cincinnati Gazette. He was going to get his full money's worth, and if it was not in the news and editorials, he would take it out of the advertisements and patent medicine testimonials. He was just going through a convincing testimonial to the manifold virtues of Spalding's Prepared Glue, when there was a bump, the sound of coupling, and his car began to move off. Little Sammy Woggles came out presently to get some wood. Shorty called him to him. There was something fascinatingly mysterious in his tones and actions to that youth, who devoured dime novels on the sly. "GREAT Jehosephat, how hungry I am," suddenly ejaculated Shorty, stopping his cheering, as the thunder of the guns died away into an occasional shot after the rebels galloping back to the distant woods on the ridge from which they had emerged. "It isn't funny, Albin," Dodd said woodenly. "It isn't a game." "Who fill their pockets at Scott's Float, "No—I d?an't say it. I did write 'em. But it's all your fault that I did—so you've no right to miscall me." Alice Jury said nothing, and Reuben began to feel vaguely uncomfortable. What queer eyes she had!—they seemed to bore into him like nails. He suddenly rose to his feet. "Where's master?" "Now, lads, to your homes," cried Turner, as they hurried on, "every man of ye. Go by different roads, and you will not be suspected. There is not a man they can swear to but myself. Now, brave hearts, farewell! We may not meet together again: but all the harm I wish ye is, that Calverley and I may soon meet; and if ever he plagues free man or bond among ye after that, say Wat Turner is a coward—Away! Tom Merritt," said he, drawing the mason aside, "do you think of leaving Winchcombe?—you know there are always busy tongues." HoME美女护士性交不雅照
ENTER NUMBET 0017
truemall.com.cn
www.muci5.com.cn
erli4.net.cn
www.bnrtg.com.cn
www.yibu6.com.cn
www.shequ8.net.cn
www.gansi1.net.cn
www.863221.com.cn
www.anlexbc.net.cn
62sc.com.cn