| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| dev:web_api:v3:changes_from_v2 [2014/07/02 10:49] – dstillman | dev:web_api:v3:changes_from_v2 [2022/06/23 15:54] (current) – dstillman |
|---|
| ====== Changes in Zotero API v3 ====== | ====== Changes in Zotero Web API v3 ====== |
| |
| Version 3 of the [[start|Zotero Web API]] introduces a new all-JSON response format and various other changes. While API v3 is mostly backwards compatible, existing clients may need to make [[#tldr_for_existing_atom_consumers|a few small adjustments]] for full compatibility, depending on usage. | Version 3 of the [[start|Zotero Web API]] introduces a new all-JSON response format and various other changes. While API v3 is mostly backwards compatible, existing clients may need to make [[#tldr_for_existing_atom_consumers|a few small adjustments]] for full compatibility, depending on usage. |
| * ''meta'' contains non-editable system-generated properties like ''createdByUser''/ ''lastModifiedByUser'' (for group items), ''creatorSummary'', and ''numChildren''. | * ''meta'' contains non-editable system-generated properties like ''createdByUser''/ ''lastModifiedByUser'' (for group items), ''creatorSummary'', and ''numChildren''. |
| * Other Atom-specific feed properties (''title'', ''author'', ''published'', ''updated'') have been removed. | * Other Atom-specific feed properties (''title'', ''author'', ''published'', ''updated'') have been removed. |
| | * Clients sending ''application/atom+xml'' in the ''Accept'' header will continue to receive Atom responses if no other format is requested |
| * For ''format=json'', ''include=data'' has replaced Atom's ''content=json'' and is now the default mode, with a top-level ''data'' object containing the editable fields. As with ''content'', additional comma-separated types can be requested (e.g., ''include=data,bib''). The requested types are provided as top-level properties. ''content=html'' remains the default in Atom. | * For ''format=json'', ''include=data'' has replaced Atom's ''content=json'' and is now the default mode, with a top-level ''data'' object containing the editable fields. As with ''content'', additional comma-separated types can be requested (e.g., ''include=data,bib''). The requested types are provided as top-level properties. ''content=html'' remains the default in Atom. |
| * Multi-object writes now take an array of JSON objects directly, rather than an object with an ''items''/''collections''/''searches'' property containing an array. | * Multi-object writes now take an array of JSON objects directly, rather than an object with an ''items''/''collections''/''searches'' property containing an array. |
| * For write requests, the API now accepts either the editable JSON (''data'') or the full parent JSON object, with the server extracting the ''data'' object automatically. The latter allows for editing tasks to be performed without any programming. | * For write requests, the API now accepts either the editable JSON (''data'') or the full parent JSON object, with the server extracting the ''data'' object automatically. The latter allows for some editing tasks to be performed without any programming. |
| * The ''parsedDate'' property in the ''format=json'' ''meta'' object gives the full parsed date in YYYY-MM-DD form, so that clients don't need to replicate Zotero's date-parsing logic to get exact dates. In v3 Atom, ''zapi:parsedDate'' replaces ''zapi:year''. | * The ''parsedDate'' property in the ''format=json'' ''meta'' object gives the full parsed date in YYYY-MM-DD form, so that clients don't need to replicate Zotero's date-parsing logic to get exact dates. In v3 Atom, ''zapi:parsedDate'' replaces ''zapi:year''. |
| * ''zapi:numTags'' is removed in v3 Atom, since it's unnecessary with the ''tags'' array in the editable json. | * ''zapi:numTags'' is removed in v3 Atom, since it's unnecessary with the ''tags'' array in the editable json. |
| ==== tl;dr for existing Atom consumers ==== | ==== tl;dr for existing Atom consumers ==== |
| |
| | * Request ''format=atom'' explicitly, or send ''application/atom+xml'' in the ''Accept'' header |
| * Use ''zapi:parsedDate'' instead of ''zapi:year'' | * Use ''zapi:parsedDate'' instead of ''zapi:year'' |
| * Use ''Total-Results'' HTTP header instead of ''zapi:totalResults'' | * Use ''Total-Results'' HTTP header instead of ''zapi:totalResults'' |
Upgrade Storage