zotero_api: Make Zotero API request

In mbojan/zoterro: Zotero Web API Interface

Make Zotero API request

Description

Fetch data from Zotero using API ver. 3. If the result is broken into multiple parts, multiple requests are made to fetch everything.

Usage

zotero_api(
  base_url = "https://api.zotero.org",
  query = NULL,
  fetch_subsequent = TRUE,
  path = NULL,
  user = zotero_usr(),
  api_key = zotero_key(),
  modified_since = NULL,
  verbose = getOption("zoterro.verbose", FALSE),
  ...
)

Arguments

base_url	Base URL of the Zotero Web API.
query	A named list of Zotero Web API URL parameters, passed on to httr::modify_url(). Note that the maximum limit is 100 results. Set fetch_subsequent = TRUE (default) to retrieve all results.
fetch_subsequent	Whether or not to also retrieve results beyond query$start + query$limit.
path	Zotero Web API resource path without the ⁠<userOrGroupPrefix>/⁠. e.g. items/top.
user	Object returned by zotero_user_id() or zotero_group_id().
api_key	Personal Zotero Web API key. See zotero_key(). If NULL, authentication is omitted, resulting in limited access to public Zotero libraries only.
modified_since	Optional Zotero library version number. If the Zotero library's content hasn't changed since the specified version number, a zero-length raw vector will be returned instead of the actual library content (and the performed API request will be significantly faster). See section Caching below for further details.
verbose	Whether or not to print called API URLs to the console.
...	Further arguments passed on to httr::RETRY().

Details

The user argument expects a Zotero user or group ID. Use zotero_user_id() or zotero_group_id() to pass it. By default zotero_usr() is called which fetches the ID from the R option zoterro.user or the environment variable ZOTERO_USER.

The URL of the request will contain the appropriate user/group ID prefix which will be combined with path or query when supplied.

By default, zotero_api() respects the following R options:

• zoterro.user (defaults to zotero_usr()): Zotero user ID.

• zoterro.key (defaults to zotero_key()): Personal Zotero Web API key.

• zoterro.verbose (defaults to FALSE): Whether or not to print called API URLs to the console.

Caching

As the official API documentation states, "every Zotero library and object (collection, item, etc.) on the server has an associated version number. The version number can be used to determine whether a client has up-to-date data for a library or object, allowing for efficient and safe syncing."

zotero_api() supports this caching mechanism via the modified_since parameter. If the Zotero library's content hasn't changed since the version number specified in modified_since, a zero-length raw vector will be returned instead of the actual library content. In this case, the performed API request will be significantly faster since the body is omitted in the corresponding HTTP response.

Otherwise, the object returned by zotero_api() has a version attribute set to the Zotero library version number returned by the API (corresponding to the current version number of the library (for multi-object requests) or object (for single-object requests)). You could provide this number as the modified_since argument to subsequent zotero_api() calls in order to use the API more efficiently (and thereby implement some form of caching).

Value

If modified_since = NULL or the Zotero library's content has changed since the specified modified_since version, a list of response objects. Otherwise, a zero-length raw vector.

In both cases, the returned object has a version attribute set to the Zotero library version number returned by the API.

Examples

## Not run: 
# Fetch groups for the default user
zotero_api(path = "groups")

# Fetch top-level collections for the group with ID=12345
zotero_api(path = "collections/top", user = zotero_group_id(12345))

## End(Not run)

mbojan/zoterro documentation built on Oct. 18, 2023, 12:10 p.m.