| Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision |
| dev:web_api:v3:basics [2019/08/25 05:45] – [Sorting and Pagination] Correct 'type' to 'itemType' dstillman | dev:web_api:v3:basics [2020/06/01 15:37] – [Caching] dstillman |
|---|
| |
| ^ Parameter ^ Values ^ Default ^ Description ^ | ^ Parameter ^ Values ^ Default ^ Description ^ |
| | | ''includeTrashed'' | ''0'', ''1'' | ''0'' (except in ''/trash'') | Include items in the trash | |
| | ''qmode'' | ''titleCreatorYear'', ''everything'' | ''titleCreatorYear'' | Quick search mode. To include full-text content, use ''everything''. Searching of other fields will be possible in the future. | | | ''qmode'' | ''titleCreatorYear'', ''everything'' | ''titleCreatorYear'' | Quick search mode. To include full-text content, use ''everything''. Searching of other fields will be possible in the future. | |
| |
| | ''sort'' | ''dateAdded'', ''dateModified'', ''title'', ''creator'', ''itemType'', ''date'', ''publisher'', ''publicationTitle'', ''journalAbbreviation'', ''language'', ''accessDate'', ''libraryCatalog'', ''callNumber'', ''rights'', ''addedBy'', ''numItems'' (tags) | ''dateModified'' (''dateAdded'' for Atom) | The name of the field by which entries are sorted | | | ''sort'' | ''dateAdded'', ''dateModified'', ''title'', ''creator'', ''itemType'', ''date'', ''publisher'', ''publicationTitle'', ''journalAbbreviation'', ''language'', ''accessDate'', ''libraryCatalog'', ''callNumber'', ''rights'', ''addedBy'', ''numItems'' (tags) | ''dateModified'' (''dateAdded'' for Atom) | The name of the field by which entries are sorted | |
| | ''direction'' | ''asc'', ''desc'' | varies by ''sort'' | The sorting direction of the field specified in the ''sort'' parameter | | | ''direction'' | ''asc'', ''desc'' | varies by ''sort'' | The sorting direction of the field specified in the ''sort'' parameter | |
| | ''limit'' | integer 1-100* | ''50'' | The maximum number of results to return with a single request. Required for export formats. | | | ''limit'' | integer 1-100* | ''25'' | The maximum number of results to return with a single request. Required for export formats. | |
| | ''start'' | integer | ''0'' | The index of the first result. Combine with the limit parameter to select a slice of the available results. | | | ''start'' | integer | ''0'' | The index of the first result. Combine with the limit parameter to select a slice of the available results. | |
| |
| ===== Caching ===== | ===== Caching ===== |
| |
| For efficient usage of the API, clients should make conditional GET requests whenever possible. If ''If-Modified-Since-Version: <libraryVersion>'' is passed with a multi-object read request (e.g., ''/users/1/items'') and data has not changed in the library since the specified version, the API will return ''304 Not Modified''. Single-object conditional requests are not currently supported, but will be supported in the future. | For efficient usage of the API, clients should make conditional GET requests whenever possible. Multi-object requests (e.g., ''/users/1/items'') return a ''Last-Modified-Version'' header with the current library version. If a ''If-Modified-Since-Version: <libraryVersion>'' header is passed with a subsequent multi-object read request and data has not changed in the library since the specified version, the API will return ''304 Not Modified'' instead of ''200''. (Single-object conditional requests are not currently supported, but will be supported in the future.) See [[syncing#version_numbers|Version Numbers]] for more information on library and object versioning and conditional requests. |
| |
| While a conditional GET request that returns a ''304'' should be fast, some clients may wish or need to perform additional caching on their own, using stored data for a period of time before making subsequent conditional requests to the Zotero API. This makes particular sense when the underlying Zotero data is known not to change frequently or when the data will be accessed frequently. For example, a website that displayed a bibliography from a Zotero collection might cache the returned bibliography for an hour, after which time it would make another conditional request to the Zotero API. If the API returned a ''304'', the website would continue to display the cached bibliography for another hour before retrying. This would prevent the website from making a request to the Zotero API every time a user loaded a page. | While a conditional GET request that returns a ''304'' should be fast, some clients may wish or need to perform additional caching on their own, using stored data for a period of time before making subsequent conditional requests to the Zotero API. This makes particular sense when the underlying Zotero data is known not to change frequently or when the data will be accessed frequently. For example, a website that displayed a bibliography from a Zotero collection might cache the returned bibliography for an hour, after which time it would make another conditional request to the Zotero API. If the API returned a ''304'', the website would continue to display the cached bibliography for another hour before retrying. This would prevent the website from making a request to the Zotero API every time a user loaded a page. |
Upgrade Storage