| Next revision | Previous revision |
| dev:web_api:v3:file_upload [2014/06/10 03:23] – external edit 127.0.0.1 | dev:web_api:v3:file_upload [2021/10/21 14:21] (current) – [ii. Register upload] dstillman |
|---|
| ====== Zotero Web API File Uploads ====== | ====== Zotero Web API File Uploads ====== |
| |
| **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.** | In addition to providing ways to [[basics#read_requests|read]] and [[write_requests|write]] online library data, the Zotero Web API allows you to upload attachment files. |
| | |
| In addition to providing ways to [[read_requests|read]] and [[write_requests|write]] online library data, the Zotero Web API allows you to upload attachment files. | |
| |
| The exact process depends on whether you are adding a new attachment file or modifying an existing one and whether you are performing a full upload or uploading a binary diff. | The exact process depends on whether you are adding a new attachment file or modifying an existing one and whether you are performing a full upload or uploading a binary diff. |
| GET /items/new?itemType=attachment&linkMode={imported_file,imported_url,linked_file,linked_url} | GET /items/new?itemType=attachment&linkMode={imported_file,imported_url,linked_file,linked_url} |
| |
| <code javascript>{ | <code>{ |
| "itemType": "attachment", | "itemType": "attachment", |
| "linkMode": "imported_url", | "linkMode": "imported_url", |
| "note": "", | "note": "", |
| "tags": [], | "tags": [], |
| | "relations": {}, |
| "contentType": "", | "contentType": "", |
| "charset": "", | "charset": "", |
| Zotero-Write-Token: <token> | Zotero-Write-Token: <token> |
| |
| <code javascript>{ | <code>[ |
| "items": [ | { |
| { | "itemType": "attachment", |
| "itemType": "attachment", | "parentItem": "ABCD2345", |
| "parentItem": "ABCD2345", | "linkMode": "imported_url", |
| "linkMode": "imported_url", | "title": "My Document", |
| "title": "My Document", | "accessDate": "2012-03-14T17:45:54Z", |
| "accessDate": "2012-03-14 17:45:54", | "url": "http://example.com/doc.pdf", |
| "url": "http://example.com/doc.pdf", | "note": "", |
| "note": "", | "tags": [], |
| "tags": [], | "relations": {}, |
| "contentType": "", | "contentType": "application/pdf", |
| "charset": "", | "charset": "", |
| "filename": "", | "filename": "doc.pdf", |
| "md5": null, | "md5": null, |
| "mtime": null | "mtime": null |
| } | } |
| ] | ]</code> |
| }</code> | |
| | |
| ''contentType'', ''charset'', ''filename'', ''md5'', and ''mtime'' can be edited directly in personal libraries for WebDAV-based file syncing. They cannot be edited directly in group libraries and should not be edited directly in personal libraries using Zotero File Storage, which provides an atomic method (detailed below) for setting the properties along with the corresponding file. | |
| |
| Top-level attachments can be created by excluding the ''parentItem'' property. As in the Zotero client, only file attachments and PDFs—not HTML snapshots or web links—can be added as top-level items. | ''md5'' and ''mtime'' can be edited directly in personal libraries for WebDAV-based file syncing. They should not be edited directly when using Zotero File Storage, which provides an atomic method (detailed below) for setting the properties along with the corresponding file. |
| |
| | Top-level attachments can be created by excluding the ''parentItem'' property or setting it to ''false''. Though the API allows all attachments to be made top-level items for backward-compatibility, it is recommended that only file attachments (''imported_file''/''linked_file'') and PDF imported web attachments (''imported_url'' with content type ''application/pdf'') be allowed as top-level items, as in the Zotero client. |
| ===== 1b) Modify an existing attachment ===== | ===== 1b) Modify an existing attachment ===== |
| |
| ==== i. Retrieve the attachment information ==== | ==== i. Retrieve the attachment information ==== |
| |
| GET /users/<userID>/items/<itemKey>?content=json | GET /users/<userID>/items/<itemKey> |
| |
| <code javascript>... | <code>{ |
| { | "key": "ABCD2345", |
| "itemType": "attachment", | "version": 124, |
| "linkMode": "imported_file", | "library": { ... }, |
| "title": "My Document", | ... |
| "note": "", | "data": { |
| "tags": [] | "key": "ABCD2345", |
| "contentType": "text/plain", | "version": 124, |
| "charset": "utf-8", | "itemType": "attachment", |
| "filename": "doc.txt", | "linkMode": "imported_file", |
| "md5": "4fa38e3f2c360ca181e633d02bab91f5", | "title": "My Document", |
| "mtime": "1331171741767" | "note": "", |
| | "tags": [], |
| | "relations": {}, |
| | "contentType": "text/plain", |
| | "charset": "utf-8", |
| | "filename": "doc.txt", |
| | "md5": "4fa38e3f2c360ca181e633d02bab91f5", |
| | "mtime": "1331171741767" |
| | } |
| } | } |
| </content> | |
| </code> | </code> |
| |
| |
| Note that to perform a faster partial upload using a binary diff, you must save a copy of the file before changes are made. | Note that to perform a faster partial upload using a binary diff, you must save a copy of the file before changes are made. |
| | |
| ===== 2) Get upload authorization ===== | ===== 2) Get upload authorization ===== |
| |
| If-None-Match: * | If-None-Match: * |
| |
| md5=<hash>&filename=<filename>&filesize=<bytes>&mtime=<milliseconds>[&contentType=<type>&charset=<charset>] | md5=<hash>&filename=<filename>&filesize=<bytes>&mtime=<milliseconds> |
| |
| For existing attachments, use ''If-Match: <hash>'' in place of ''If-None-Match: *'', where <hash> is the previous MD5 hash of the file (as provided in the ''ETag'' header when downloading it). | For existing attachments, use ''If-Match: <hash>'' in place of ''If-None-Match: *'', where <hash> is the previous MD5 hash of the file (as provided in the ''ETag'' header when downloading it). |
| A successful ''200'' response returns one of two possible JSON objects: | A successful ''200'' response returns one of two possible JSON objects: |
| |
| <code javascript>{ | <code>{ |
| "url": ..., | "url": ..., |
| "contentType": ..., | "contentType": ..., |
| or | or |
| |
| <code javascript>{ "exists": 1 }</code> | <code>{ "exists": 1 }</code> |
| |
| In the latter case, the file already exists on the server and was successfully associated with the specified item. No further action is necessary. | In the latter case, the file already exists on the server and was successfully associated with the specified item. No further action is necessary. |
| Concatenate ''prefix'', the file contents, and ''suffix'' and POST to ''url'' with the ''Content-Type'' header set to ''contentType''. | Concatenate ''prefix'', the file contents, and ''suffix'' and POST to ''url'' with the ''Content-Type'' header set to ''contentType''. |
| |
| 'prefix' and 'suffix' are strings containing multipart/form-data. In some environments, it may be easier to work directly with the form parameters. Add params=1 to the upload authorization request above to retrieve the individual parameters in a ''params'' array, which will replace ''contentType'', ''prefix'', and ''suffix''. | ''prefix'' and ''suffix'' are strings containing multipart/form-data. In some environments, it may be easier to work directly with the form parameters. Add ''params=1'' to the upload authorization request above to retrieve the individual parameters in a ''params'' array, which will replace ''contentType'', ''prefix'', and ''suffix''. |
| |
| ^ Common responses ^^ | ^ Common responses ^^ |
| |
| |
| After the upload has been registered, the attachment item will reflect the new metadata. | After the upload has been registered, the attachment item will reflect the new metadata (''filename'', ''mtime'', ''md5''). |
| |
| |
| For best results, we recommend using Xdelta version 3 with the "''-9 -S djw''" flags. bsdiff takes significantly longer to generate diffs. 'vcdiff' is an alias for 'xdelta', as Xdelta3 can process diffs in VCDIFF format. | For best results, we recommend using Xdelta version 3 with the "''-9 -S djw''" flags. bsdiff takes significantly longer to generate diffs. 'vcdiff' is an alias for 'xdelta', as Xdelta3 can process diffs in VCDIFF format. |
| |
| Clients may wish to automatically fall back to a full upload---possibly with some form of warning---if HTTP PATCH is not supported by a user's proxy server (indicated, in theory, by a ''405 Method Not Allowed''). | Clients may wish to automatically fall back to a full upload — possibly with some form of warning — if HTTP PATCH is not supported by a user's proxy server (indicated, in theory, by a ''405 Method Not Allowed''). |
| |
| After the upload has finished, the attachment item will reflect the new metadata. | After the upload has finished, the attachment item will reflect the new metadata. |
Upgrade Storage