| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| dev:web_api:v3:file_upload [2014/06/13 03:41] – dstillman | dev:web_api:v3:file_upload [2021/10/21 14:21] (current) – [ii. Register upload] dstillman |
|---|
| <html><p style="color:red; font-weight:bold">This is draft documentation. APIv3 is not yet available for use.</p></html> | |
| |
| ====== Zotero Web API File Uploads ====== | ====== Zotero Web API File Uploads ====== |
| |
| **This is not currently the default [[basics#api_versioning|version]] of the API. Include the ''Zotero-API-Version: 3'' HTTP header or the ''v=3'' query parameter 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 [[basics#read_requests|read]] and [[write_requests|write]] online library data, the Zotero Web API allows you to upload attachment files. |
| "note": "", | "note": "", |
| "tags": [], | "tags": [], |
| | "relations": {}, |
| "contentType": "", | "contentType": "", |
| "charset": "", | "charset": "", |
| Zotero-Write-Token: <token> | Zotero-Write-Token: <token> |
| |
| <code>{ | <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-14T17:45:54Z", | "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 or setting it to ''false''. 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 ===== |
| |
| "title": "My Document", | "title": "My Document", |
| "note": "", | "note": "", |
| "tags": [] | "tags": [], |
| | "relations": {}, |
| "contentType": "text/plain", | "contentType": "text/plain", |
| "charset": "utf-8", | "charset": "utf-8", |
| } | } |
| } | } |
| </content> | |
| </code> | </code> |
| |
| 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). |
| |
| |
| 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''). |
| |
| |
Upgrade Storage