| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| dev:web_api:v3:write_requests [2018/12/28 02:52] – [JSON Object Data] Removing the Expect header in cURL no longer seems to be required dstillman | dev:web_api:v3:write_requests [2021/06/02 16:30] (current) – [Creating Multiple Objects] dstillman |
|---|
| |
| <code> | <code> |
| $ URL="https://api.zotero.org/users/1234567/items?key=P9NiFoyLeZu2bZNvvuQPDWsd" | $ URL="https://api.zotero.org/users/1234567/items" |
| $ curl $URL > items.json | $ API_KEY="P9NiFoyLeZu2bZNvvuQPDWsd" |
| | $ curl -H "Zotero-API-Key: $API_KEY" $URL > items.json |
| $ vi items.json # edit the item data | $ vi items.json # edit the item data |
| $ curl -d @items.json -v $URL | $ curl -H "Zotero-API-Key: $API_KEY" -d @items.json -v $URL |
| </code> | </code> |
| |
| |
| 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. | 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: |
| | |
| | <code> |
| | $ 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 |
| | </code> |
| |
| Note that when uploading full JSON, only the ''data'' property is processed. All other properties (''library'', ''links'', ''meta'', etc.) are ignored. | Note that when uploading full JSON, only the ''data'' property is processed. All other properties (''library'', ''links'', ''meta'', etc.) are ignored. |
| POST <userOrGroupPrefix>/items | POST <userOrGroupPrefix>/items |
| 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>[ |
| |
| PATCH <userOrGroupPrefix>/items/<itemKey> | PATCH <userOrGroupPrefix>/items/<itemKey> |
| If-Unmodified-Since-Version: <version> | If-Unmodified-Since-Version: <last item version> |
| |
| <code>{ | <code>{ |
| === 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 ^^ |
| |
| 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 ^^ |
| |
| DELETE <userOrGroupPrefix>/items?itemKey=<key>,<key>,<key> | DELETE <userOrGroupPrefix>/items?itemKey=<key>,<key>,<key> |
| 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> |
| |
| |
| |
| 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 ^^ |
| |
| 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> |
| |
| |
| |
| 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 ^^ |
| |
| 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> |
| |
| |
| POST <userOrGroupPrefix>/collections | POST <userOrGroupPrefix>/collections |
| Content-Type: application/json | Content-Type: application/json |
| Zotero-Write-Token: <write token> | |
| |
| <code>[ | <code>[ |
| ]</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>{ |
| "success": { | "successful": { |
| "0": "<objectKey>", | "0": "<saved object>", |
| "2": "<objectKey>" | "2": "<saved object>" |
| }, | }, |
| "unchanged": { | "unchanged": { |
| }</code> | }</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 any Zotero objects in the ''success'' object --- that is, objects that were modified in this request. | 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 ^^ | ^ Common responses ^^ |
| | ''200 OK'' | The objects were uploaded. | | | ''200 OK'' | The objects were uploaded. | |
| | ''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. | |
| |
| |
| |
| 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 ===== |
Upgrade Storage