| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| dev:web_api:v3:basics [2022/10/25 02:24] – [Search Parameters] dstillman | dev:web_api:v3:basics [2024/04/07 07:24] (current) – [Rate Limiting] dstillman |
|---|
| ===== Caching ===== | ===== Caching ===== |
| |
| 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. | 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.) |
| |
| 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. |
| |
| | In addition to making conditional requests, clients downloading data for entire Zotero libraries should use ''?since='' to request only objects that have changed since the last time data was downloaded. |
| | |
| | See [[syncing|Syncing]] for more information on library and object versioning. |
| ===== Rate Limiting ===== | ===== Rate Limiting ===== |
| |
| If the API servers are overloaded, the API may include a ''Backoff: <seconds>'' HTTP header in responses, indicating that the client should perform the minimum number of requests necessary to maintain data consistency and then refrain from making further requests for the number of seconds indicated. ''Backoff'' can be included in any response, including successful ones. | If the API servers are overloaded, the API may include a ''Backoff: <seconds>'' HTTP header in responses, indicating that the client should perform the minimum number of requests necessary to maintain data consistency and then refrain from making further requests for the number of seconds indicated. ''Backoff'' can be included in any response, including successful ones. |
| |
| If a client has made too many requests within a given time period, the API may return ''429 Too Many Requests'' with a ''Retry-After: <seconds>'' header. Clients receiving a ''429'' should wait the number of seconds indicated in the header before retrying the request. | If a client has made too many requests within a given time period or is making too many concurrent requests, the API may return ''429 Too Many Requests'' with a ''Retry-After: <seconds>'' header. Clients receiving a ''429'' should wait at least the number of seconds indicated in the header before making further requests. They should also reduce their overall request rate and/or concurrency to avoid repeatedly getting 429s, which may result in stricter throttling or temporary blocks. |
| |
| ''Retry-After'' can also be included with ''503 Service Unavailable'' responses when the server is undergoing maintenance. | ''Retry-After'' can also be included with ''503 Service Unavailable'' responses when the server is undergoing maintenance. |
Upgrade Storage