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 [2019/02/05 03:43]
dstillman [Resources]
dev:web_api:v3:basics [2019/08/18 01:55] (current)
dstillman [Read Requests]
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>'',​ 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.+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 ^
 +| ''​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 ====
dev/web_api/v3/basics.1549356231.txt.gz · Last modified: 2019/02/05 03:43 by dstillman