Skip to contents

Perform one Zotero API request

zotRequest.Rd

Core transport for every zot API call: bounded retries, Backoff and Retry-After honoring, and conditional writes through If-Unmodified-Since-Version. Returns for every HTTP status — callers interpret status (a 404 is a verdict, not a transport failure); only an exhausted transport raises a zotHttpError.

Usage

zotRequest(config, method, path, query = list(), body = NULL, version = NULL)

zotGet(config, path, query = list())

zotPost(config, path, body)

zotPatch(config, path, body, version)

Arguments

config

A zotConfig() object.

method

HTTP method: "GET", "POST" or "PATCH".

path

API path starting at the host root (see zotLibraryPath()).

query

Named list of query parameters.

body

Request body, serialized as JSON when not NULL.

version

Value for If-Unmodified-Since-Version; required by zotPatch() so no write is unconditional.

Value

A list with status, headers (named list) and body (parsed JSON, or NULL when empty).

Details

A performer receives config, method, path, query, body, and version, and returns a list with status, headers, and body. This makes the complete HTTP boundary replaceable in examples and tests without changing the public request contract. Responses eligible for retry are bounded by five attempts; other HTTP statuses are returned unchanged. POST is retried only after rate limiting (HTTP 429). A server failure on POST can follow an effect, so it is returned without another write; the guarded executor retains that unknown outcome as an attempt. GET and versioned PATCH retain their retries on HTTP 500, 502 and 503.

See also

zotGetAll(), zotTrash(), and zotPreview().

Examples

Performer <- function(config, method, path, query, body, version) {
  list(
    status = if (method == "POST") 201L else 200L,
    headers = list(),
    body = list(method = method, path = path, body = body, version = version)
  )
}
Config <- structure(
  list(userID = "42", key = "example", apiBase = "https://example.invalid",
       performer = Performer),
  class = "zotConfig"
)
zotGet(Config, path = "/users/42/items/ABCD1234")$status
#> [1] 200
zotPost(Config, path = "/users/42/items", body = list(list(title = "New")))$status
#> [1] 201
zotPatch(Config, path = "/users/42/items/ABCD1234",
         body = list(title = "Revised"), version = 7L)$body$version
#> [1] 7