Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
Next revisionBoth sides next revision
dev:web_api:v3:basics [2018/12/17 03:35] – [Read Requests] dstillmandev:web_api:v3:basics [2020/04/30 05:47] – [Searching] Add includeTrashed param dstillman
Line 46: Line 46:
 ==== User and Group Library URLs ==== ==== User and Group Library URLs ====
  
-Requests for data in a specific library begin with ''/users/<userID>'' or ''/groups/<groupID>''. User IDs are different from usernames and can be found on the [[/settings/keys|API Keys]] page and in OAuth responses.+Requests for data in a specific library begin with ''/users/<userID>'' or ''/groups/<groupID>'', referred to below as ''<userOrGroupPrefix>''. User IDs are different from usernames and can be found on the [[/settings/keys|API Keys]] page and in OAuth responses. Group IDs are different from group names and can be retrieved from ''/users/<userID>/groups''
 + 
 +=== Collections ===
  
 ^ URI ^ Description ^ ^ URI ^ Description ^
-| <userOrGroupPrefix>/items | The set of all items in the library, excluding trashed items | +| <userOrGroupPrefix>/collections | Collections in the library | 
-| <userOrGroupPrefix>/items/top | The set of all top-level items in the library, excluding trashed items | +| <userOrGroupPrefix>/collections/top | Top-level collections in the library |
-| <userOrGroupPrefix>/items/trash | The set of items in the trash | +
-| <userOrGroupPrefix>/items/<itemKey> | A specific item in the library | +
-| <userOrGroupPrefix>/items/<itemKey>/children | The set of all child items under a specific item | +
-| <userOrGroupPrefix>/items/<itemKey>/tags | The set of all tags associated with a specific item | +
-| <userOrGroupPrefix>/tags | The set of all tags in the library | +
-| <userOrGroupPrefix>/tags/<url+encoded+tag> | The set of tags (i.e., of all types) matching a specific name | +
-| <userOrGroupPrefix>/collections | The set of all collections in the library | +
-| <userOrGroupPrefix>/collections/top | The set of all top-level collections in the library |+
 | <userOrGroupPrefix>/collections/<collectionKey> | A specific collection in the library | | <userOrGroupPrefix>/collections/<collectionKey> | A specific collection in the library |
-| <userOrGroupPrefix>/collections/<collectionKey>/collections | The set of subcollections within a specific collection in the library | +| <userOrGroupPrefix>/collections/<collectionKey>/collections | Subcollections within a specific collection in the library | 
-| <userOrGroupPrefix>/collections/<collectionKey>/items | The set of all items within a specific collection in the library | + 
-| <userOrGroupPrefix>/collections/<collectionKey>/items/top The set of top-level items within a specific collection in the library | +=== Items === 
-| <userOrGroupPrefix>/collections/<collectionKey>/tags The set of tags within a specific collection in the library | + 
-| <userOrGroupPrefix>/searches | The set of all saved searches in the library |+^ URI ^ Description ^ 
 +| <userOrGroupPrefix>/items | All items in the library, excluding trashed items | 
 +| <userOrGroupPrefix>/items/top | Top-level items in the library, excluding trashed items | 
 +<userOrGroupPrefix>/items/trash Items in the trash | 
 +| <userOrGroupPrefix>/items/<itemKey> | A specific item in the library | 
 +| <userOrGroupPrefix>/items/<itemKey>/children | Child items under a specific item |  
 +| <userOrGroupPrefix>/publications/items Items in My Publications | 
 +| <userOrGroupPrefix>/collections/<collectionKey>/items | Items within a specific collection in the library | 
 +| <userOrGroupPrefix>/collections/<collectionKey>/items/top Top-level items within a specific collection in the library | 
 + 
 +=== Searches === 
 + 
 +(Note: Only search metadata is currently available, not search results.) 
 + 
 +^ URI ^ Description ^ 
 +| <userOrGroupPrefix>/searches | All saved searches in the library |
 | <userOrGroupPrefix>/searches/<searchKey> | A specific saved search in the library | | <userOrGroupPrefix>/searches/<searchKey> | A specific saved search in the library |
 +
 +=== Tags ===
 +
 +^ URI ^ Description ^
 +| <userOrGroupPrefix>/tags | All tags in the library |
 +| <userOrGroupPrefix>/tags/<url+encoded+tag> | Tags of all types matching a specific name |
 +| <userOrGroupPrefix>/items/<itemKey>/tags | Tags associated with a specific item |
 +| <userOrGroupPrefix>/collections/<collectionKey>/tags | Tags within a specific collection in the library |
 +| <userOrGroupPrefix>/items/tags | All tags in the library, with the ability to filter based on the items |
 +| <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>/items/<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 |
 +
 +
  
 ==== Other URLs ==== ==== Other URLs ====
Line 98: Line 123:
 ^ Parameter ^ Values ^ Default ^ Description ^ ^ Parameter ^ Values ^ Default ^ Description ^
 | ''style'' | string | ''chicago-note-bibliography'' | Citation style to use for formatted references. Can be either the file name (without the .csl extension) of one of the styles in the [[https://www.zotero.org/styles/|Zotero Style Repository]] (e.g., ''apa'') or the URL of a remote CSL file. | | ''style'' | string | ''chicago-note-bibliography'' | Citation style to use for formatted references. Can be either the file name (without the .csl extension) of one of the styles in the [[https://www.zotero.org/styles/|Zotero Style Repository]] (e.g., ''apa'') or the URL of a remote CSL file. |
 +| ''linkwrap'' | boolean | ''0'' | Set to ''1'' to return URLs and DOIs as links |
 | ''locale'' | string | ''en-US'' | Bibliography locale. See the [[https://github.com/citation-style-language/locales|available CSL locales]]. Note that some styles use a fixed locale and cannot be localized. | | ''locale'' | string | ''en-US'' | Bibliography locale. See the [[https://github.com/citation-style-language/locales|available CSL locales]]. Note that some styles use a fixed locale and cannot be localized. |
  
Line 131: Line 157:
 | ''itemType'' | [[#search_syntax|search syntax]] | null | Item type search | | ''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. | | ''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. |
-| ''qmode'' | ''titleCreatorYear'', ''everything'' | ''titleCreatorYear'' | Quick search mode. To include full-text content in the search, use ''everything''. Searching of other fields will be possible in the future. | 
 | ''since'' | integer | ''0'' | Return only objects modified after the specified library verson. | | ''since'' | integer | ''0'' | Return only objects modified after the specified library verson. |
 | ''tag'' | [[#search_syntax|search syntax]] | null | Tag search | | ''tag'' | [[#search_syntax|search syntax]] | null | Tag search |
 +
 +==== Search Parameters (Items Endpoints) ====
 +
 +^ 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. |
 +
 +==== Search Parameters (Tags Endpoints) ====
 +
 +^ Parameter ^ Values ^ Default ^ Description ^
 +| ''qmode'' | ''contains'', ''startsWith'' | ''contains'' | Quick search mode. To perform a left-bound search, use ''startsWith''. |
 +
 +==== Search Parameters (Tags-Within-Items Endpoints) ====
 +
 +These parameters can be used to search against items when returning tags within items. In such cases, the main parameters (''q'', ''qmode'', ''tag'') apply to the tags themselves, as the primary objects of the request.
 +
 +^ Parameter ^ Values ^ Default ^ Description ^
 +| ''itemQ'' | string | null | Same as ''q'' in an ''items'' request | 
 +| ''itemQMode'' | ''contains'', ''startsWith'' | ''contains'' | Same as ''qmode'' in an ''items'' request |
 +| ''itemTag'' | [[#search_syntax|search syntax]] | null | Same as ''tag'' in an ''items'' request |
 +
  
 ==== Search Syntax ==== ==== Search Syntax ====
Line 162: Line 208:
  
 ^ Parameter ^ Values ^ Default ^ Description ^ ^ Parameter ^ Values ^ Default ^ Description ^
-| ''sort'' | ''dateAdded'', ''dateModified'', ''title'', ''creator'', ''type'', ''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. |
  
dev/web_api/v3/basics.txt · Last modified: 2023/02/05 23:45 by dstillman