| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| dev:web_api:v3:changes_from_v2 [2014/06/07 02:00] – dstillman | dev:web_api:v3:changes_from_v2 [2022/06/23 15:54] (current) – dstillman |
|---|
| 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 a few small adjustments for full compatibility, depending on usage. | ====== Changes in Zotero Web API v3 ====== |
| |
| ==== Changes in 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. |
| |
| * New default all-JSON response format, ''format=json'' | * New default all-JSON response format, ''format=json'' |
| * Contains a single JSON object for single-object requests and an array of objects for multi-object requests | * Contains a single JSON object for single-object requests and an array of objects for multi-object requests |
| * All individual objects contain top-level ''key'' and ''version'' properties and top-level ''library'', ''links'', and ''meta'' objects. | * All individual objects contain top-level ''key'' and ''version'' properties and top-level ''library'', ''links'', and ''meta'' objects. |
| * ''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. |
| * 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''. | * 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. |
| | * 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''. |
| * ''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. |
| | * The API now returns 25 results per request instead of 50 if ''limit'' isn't provided. |
| * The total result count for multi-object responses is available in a new custom HTTP header, ''Total-Results''. ''zapi:totalResults'' is removed in v3 Atom. | * The total result count for multi-object responses is available in a new custom HTTP header, ''Total-Results''. ''zapi:totalResults'' is removed in v3 Atom. |
| * ''rel=first''/''prev''/''next''/''last''/''alternate'' links for multi-object responses are now provided in the ''Link'' HTTP header. | * ''rel=first''/''prev''/''next''/''last''/''alternate'' links for multi-object responses are now provided in the ''Link'' HTTP header. |
| * ''itemKey''/''itemVersion'' (and similar properties on collections and searches) in the editable JSON are now just ''key'' and ''version'' for easier handling by clients. Clients that simply pass back the edited JSON without touching those properties shouldn't be affected. Clients that store the JSON will need to modify it before sending in v3. | * ''itemKey''/''itemVersion'' (and similar properties on collections and searches) in the editable JSON are now just ''key'' and ''version'' for easier handling by clients. Clients that simply pass back the edited JSON without touching those properties shouldn't be affected. Clients that store the JSON will need to modify it before sending in v3. |
| * The ''version'' metadata field in the ''computerProgram'' item type is now ''versionNumber'' to avoid a conflict with the renamed object version property. | * The ''version'' metadata field in the ''computerProgram'' item type is now ''versionNumber'' to avoid a conflict with the renamed object version property. |
| * dateAdded/dateModified are included in the 'data' object in ISO 8601 form. Previously these timestamps were provided only in the Atom ''published''/''updated'' elements, though in v2 they can be sent back in the JSON as ''dateAdded''/''dateModified'' in SQL DATETIME format, interpreted as UTC. In v3 write requests, either is accepted, though SQL DATETIME is deprecated. | * dateAdded/dateModified are included in the 'data' object in ISO 8601 form. Previously these timestamps were provided only in the Atom ''published''/''updated'' elements, though in v2 they can be sent back in the JSON as ''dateAdded''/''dateModified'' in YYYY-MM-DD hh-mm-dd format, interpreted as UTC. In v3 write requests, either is accepted, though the previous form is deprecated. |
| * The ''accessDate'' field, which was also previously an SQL DATETIME, is ISO 8601 in v3 (including in Atom) for both reading and writing. SQL DATETIME is accepted but deprecated. | * The ''accessDate'' field, which was also previously YYYY-MM-DD[ hh-mm-dd], is ISO 8601 in v3 (including in Atom) for both reading and writing. The previous form is accepted but deprecated. |
| * The pagination links (''rel=self''/''first''/''prev''/''next''/''last'') on multi-object responses can be used without modification by clients using the ''Authorization'' header. The ''rel=self'' links in individual objects are meant as base URIs and do not include any query parameters (e.g., ''include=data,bib''). This is a change from the previous behavior, where the Atom entry ''rel="self"'' links include all non-default provided parameters. But with the ''Authorization'' header and ''include=data'' as the new default, the base URI may be sufficient for most individual-object requests. | * The pagination links (''rel=self''/''first''/''prev''/''next''/''last'') on multi-object responses can be used without modification by clients using the ''Authorization'' header. The ''rel=self'' links in individual objects are meant as base URIs and do not include any query parameters (e.g., ''include=data,bib''). This is a change from the previous behavior, where the Atom entry ''rel="self"'' links include all non-default provided parameters. But with the ''Authorization'' header and ''include=data'' as the new default, the base URI may be sufficient for most individual-object requests. |
| * The ''newer'' parameter is now ''since'' for clarity. ''newer'' is deprecated. | * The ''newer'' parameter is now ''since'' for clarity. ''newer'' is deprecated. |
| * '<', '>', and '&' are no longer unnecessarily escaped to \u.... in returned JSON data. In Atom, these characters are instead turned into XML numeric character references. Proper XML and JSON parsers shouldn't be affected by these changes. | * '<', '>', and '&' are no longer unnecessarily escaped to \u.... in returned JSON data. In Atom, these characters are instead turned into XML numeric character references. Proper XML and JSON parsers shouldn't be affected by these changes. |
| * The HTTP Warning header may be used to send clients non-fatal warnings — such as deprecation warnings — that can be logged. | * The HTTP Warning header may be used to send clients non-fatal warnings — such as deprecation warnings — that can be logged. |
| * New recommendation: Clients that store editable JSON should save the current API version alongside the JSON. When the clients are later updated for an API version that changes how passed JSON is handled, they will need to make changes to the stored JSON or retrieve it again before sending it up. | |
| | |
| ==== 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'' |
| * Count the ''tags'' array in content JSON instead of using ''zapi:numTags'' | * Count the ''tags'' array in editable JSON instead of using ''zapi:numTags'' |
| * Use ''key''/''version'' instead of ''itemKey''/''itemVersion'' (and ''collection*''/''search*'') in content JSON | * Use ''key''/''version'' instead of ''itemKey''/''itemVersion'' (and ''collection*''/''search*'') in editable JSON |
| * Use ''versionNumber'' instead of ''version'' metadata field in ''computerProgram'' item type | * Use ''versionNumber'' instead of ''version'' metadata field in ''computerProgram'' item type |
| * Use ISO 8601 dates for ''accessDate'', ''dateAdded'', and ''dateModified'' | * Use ISO 8601 dates for ''accessDate'', ''dateAdded'', and ''dateModified'' |
| * Use ''since'' parameter instead of ''newer'' | * Use ''since'' parameter instead of ''newer'' |
| * Use ''sort'' parameter instead of ''order'' and ''direction'' instead of ''sort'' | * Use ''sort'' parameter instead of ''order'' and ''direction'' instead of ''sort'' |
| | * For writes, upload an array of JSON objects directly instead of an object containing an ''items''/''collections''/''searches'' array |
| * Optionally, use ''Authorization: Bearer <apiKey>'' instead of ''key'' parameter | * Optionally, use ''Authorization: Bearer <apiKey>'' instead of ''key'' parameter |
| * Use ''v'' parameter instead of ''Zotero-API-Version'' for debugging | * Optionally, use ''v'' parameter instead of ''Zotero-API-Version'' for debugging |
Upgrade Storage