Differences

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

--- dev:web_api:v3:basics [2019/08/25 05:45] – [Sorting and Pagination] Correct 'type' to 'itemType' dstillman
+++ dev:web_api:v3:basics [2024/04/07 07:24] (current) – [Rate Limiting] dstillman
@@ Line 86: / Line 86: @@
 | <userOrGroupPrefix>/items/top/tags | Tags assigned to top-level items |
 | <userOrGroupPrefix>/items/trash/tags | Tags assigned to items in the trash |
-| <userOrGroupPrefix>/items/<collectionKey>/items/tags | Tags assigned to items in a given collection |
+| <userOrGroupPrefix>/collections/<collectionKey>/items/tags | Tags assigned to items in a given collection |
-| <userOrGroupPrefix>/items/<collectionKey>/items/top/tags | Tags assigned to top-level items in a given collection |
+| <userOrGroupPrefix>/collections/<collectionKey>/items/top/tags | Tags assigned to top-level items in a given collection |
 | <userOrGroupPrefix>/publications/items/tags | Tags assigned to items in My Publications |
@@ Line 129: / Line 129: @@
 Note the difference between ''format=bib'' and ''include=bib''/''content=bib''. ''format=bib'' returns a formatted bibliography as XHTML, sorted according to the rules of the selected style. ''include=bib'' (valid only for ''format=json'' (the default format mode) and ''format=atom'') returns an individual formatted reference within the JSON ''data'' block or Atom ''<content>'' block for each item, with the results or feed sorted according to the query parameters. ''format=bib'' processes the entire feed you are requesting without regard for any limit arguments, so it is generally a good idea to use it only with collections or tags.
-==== Export Formats ====
+==== Item Export Formats ====
-The following bibliographic data formats can be used as ''format'', ''include'', and ''content'' parameters:
+The following bibliographic data formats can be used as ''format'', ''include'', and ''content'' parameters for items requests:
 ^ Parameter ^ Description ^
@@ Line 139: / Line 139: @@
 | ''coins'' | COinS |
 | ''csljson'' | [[https://github.com/citation-style-language/schema/blob/master/csl-data.json|Citation Style Language data format]] |
+| ''csv'' | CSV |
 | ''mods'' | MODS |
 | ''refer'' | Refer/BibIX |
@@ Line 157: / Line 158: @@
 | ''itemType'' | [[#search_syntax|search syntax]] | null | Item type search |
 | ''q'' | string | null | Quick search. Searches titles and individual creator fields by default. Use the ''qmode'' parameter to change the mode. Currently supports phrase searching only. |
-| ''since'' | integer | ''0'' | Return only objects modified after the specified library verson. |
+| ''since'' | integer | ''0'' | Return only objects modified after the specified library version, returned in a previous ''Last-Modified-Version'' header. See [[Syncing]] for more info. |
 | ''tag'' | [[#search_syntax|search syntax]] | null | Tag search |
@@ Line 163: / Line 164: @@
 ^ 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. |
@@ Line 209: / Line 211: @@
 | ''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 |
-| ''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. |
@@ Line 233: / Line 235: @@
 ===== 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.)
 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 =====
@@ Line 245: / Line 250: @@
 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.