Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
dev:web_api:v3:basics [2020/02/10 14:25]
dstillman [Sorting and Pagination]
dev:web_api:v3:basics [2020/06/01 15:37]
dstillman [Caching]
Line 163: Line 163:
  
 ^ 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. |
  
Line 233: Line 234:
 ===== 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 ''​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.
dev/web_api/v3/basics.txt · Last modified: 2020/06/01 15:37 by dstillman