zotero-api-client

v0.51.0

Published

22 days ago

A lightweight, minimalistic Zotero API client

0High
0Medium
0Low

tnajdek

Zotero API client

A lightweight, minimalistic Zotero API client developed in JavaScript with the following goals:

Small, single-purpose module: focuses solely on interacting with the API
Compatible with both Node and browser environments
No abstraction over Zotero data: what you see is what you get
Clean API
Small bundle footprint
Minimal request validation
Predictable and consistent responses
Full test coverage

The client does not provide the following:

Version management: version headers need to be provided explicitly
Caching: each call to get(), post(), etc., actually calls the API
Abstraction: there are no Item or Collection objects. The API response is returned with a minimal layer to automate common tasks and offers unrestricted access to the raw response JSON data.

Getting The Library

The NPM package includes the source of the library, which can be used as part of your build process (e.g., with Browserify, Rollup, Webpack, etc.) or directly in Node:

npm install zotero-api-client

The package also includes a UMD bundle, which can be loaded with common module loaders or included directly in a <script> tag. In the latter case, the library will be available as a global object ZoteroApiClient. One way to use the UMD bundle on your page is to include it from the unpkg project CDN:

<script src="https://unpkg.com/zotero-api-client"></script>

Example

A simple example of reading items from the public/test user library:

Import the library based on your environment:

// ES module, commonly used with a bundler:
import api from 'zotero-api-client';
// CommonJS, for Node.js and some bundling cases:
const { default: api } = require('zotero-api-client');
// UMD bundle creates `ZoteroApiClient` global object
const { default: api } = ZoteroApiClient;

Use the API to make the request (using async functions):

const response = await api().library('user', 475425).collections('9KH9TNSJ').items().get();

Extract items from the response:
```
const items = response.getData();
```
Print the titles of all items in the collection to the console:
```
console.log(items.map(i => i.title));
```

Overview

The library is composed of three layers:

api function: This is the only interface exported for use.
Request engine: This component does the heavy lifting and should not be used directly.
ApiResponse class: A thin wrapper around the response. Multiple specialised variants exist for handling different response types.

API interface

The API interface is a function that returns a set of functions bound to previously configured options, allowing it to be chained and stored in a partially configured state. A common scenario is to store authentication and library details, which can be done as follows:

import api from 'zotero-api-client';
const myapi = api('AUTH_KEY').library('user', 0);

This produces an API client already configured with your credentials and user library ID. You can now use myapi to obtain the list of collections in that library:

const collectionsResponse = await myapi.collections().get();

Items in that library:

const itemsResponse = await myapi.items().get();

Or items in a specific collection:

const collectionItemsResponse = await myapi.collections('EXAMPLE1').items().get();

There are two types of API functions:

Configuration functions (e.g., items()) that can be further chained.
Execution functions (e.g., get()) that trigger the request.

For a complete reference, see the documentation for api().

Response

The response is an instance of a specialised response class object returned by one of the execution functions of the api. Each response includes a specialised getData() method, which returns the entities that were requested or modified, depending on the request configuration.

For a complete reference, see the documentation for SingleReadResponse, MultiReadResponse, SingleWriteResponse, MultiWriteResponse, DeleteResponse, FileUploadResponse, FileDownloadResponse, FileUrlResponse.

Request

The request function takes a configuration object generated by the API interface, communicates with the API, and returns one of the response objects (see above). Some rarely used properties cannot be configured through API configuration functions and must be specified as optional properties when calling api() or one of the API's execution functions.

For a complete list of all properties request() accepts, please refer to the documentation for request().

Local API

The Zotero desktop application can serve a local version of the API at http://localhost:23119/api/ (enable "Allow other applications on this computer to communicate with Zotero" in Zotero's Advanced settings). It mirrors the web API, user ID 0 refers to the local profile's user. Read requests require no API key:

const localapi = api('', { apiScheme: 'http', apiAuthorityPart: 'localhost:23119', apiPath: 'api/' });
const response = await localapi.library('user', 0).items().get();

Write requests require two extra pieces:

Server ID: every write must carry a Zotero-Server-ID header identifying the Zotero instance. Every local API response includes this header, so it can be bootstrapped with a bare root request.
Local API key: requested with local().authorize(), which makes Zotero prompt the user to allow write access for your app.

const serverID = (await localapi.get()).getServerID();
const auth = await localapi.serverID(serverID).local().authorize('My App').post();
const key = auth.getKey();

If the user picks "Always allow", auth.isRemembered() returns true and the key remains valid until revoked in Zotero's settings. Otherwise the key is single-use: it is consumed by the first write request, and a write with a used or unknown key fails with 401, at which point authorization should be requested again.

With both in hand, writes look exactly like web API writes:

await api(key, { apiScheme: 'http', apiAuthorityPart: 'localhost:23119', apiPath: 'api/' })
	.library('user', 0).serverID(serverID).items().post([ /* items */ ]);

Note: the local API drops requests that appear to come from a browser (a Mozilla/ user agent or an Origin header) unless the Zotero-Allowed-Request header is present; set it via the zoteroAllowedRequest option.

API Reference

zotero-api-client
- ~ApiResponse
  - .getResponseType() ⇒ string
  - .getData() ⇒ object
  - .getLinks() ⇒ object
  - .getMeta() ⇒ object
  - .getVersion() ⇒ number
  - .getServerID() ⇒ string
- ~FullTextStatusResponse ⇐ ApiResponse
  - .getResponseType()
  - .getStatus() ⇒ string
  - .getIndexedCount() ⇒ number
  - .getExpectedCount() ⇒ number
- ~SingleReadResponse ⇐ ApiResponse
  - .getResponseType()
  - .getData() ⇒ Object
- ~MultiReadResponse ⇐ ApiResponse
  - .getResponseType()
  - .getData() ⇒ Array
  - .getLinks() ⇒ Array
  - .getMeta() ⇒ Array
  - .getTotalResults() ⇒ number
  - .getRelLinks() ⇒ object
- ~SingleWriteResponse ⇐ ApiResponse
  - .getResponseType()
  - .getData() ⇒ Object
- ~MultiWriteResponse ⇐ ApiResponse
  - .getResponseType()
  - .isSuccess() ⇒ Boolean
  - .getData() ⇒ Array
  - .getLinks()
  - .getMeta()
  - .getErrors() ⇒ Object
  - .getEntityByKey(key) ⇒ Object
  - .getEntityByIndex(index) ⇒ Object
- ~DeleteResponse ⇐ ApiResponse
  - .getResponseType()
- ~AuthorizeResponse ⇐ ApiResponse
  - .getResponseType()
  - .getKey() ⇒ string
  - .isRemembered() ⇒ boolean
- ~FileUploadResponse ⇐ ApiResponse
  - .getResponseType()
  - .getVersion()
- ~FileDownloadResponse ⇐ ApiResponse
  - .getResponseType()
- ~FileUrlResponse ⇐ ApiResponse
  - .getResponseType()
- ~RawApiResponse ⇐ ApiResponse
  - .getResponseType()
- ~PretendResponse ⇐ ApiResponse
  - .getResponseType()
  - .getVersion() ⇒ Object
- ~ErrorResponse ⇐ Error
  - .getVersion() ⇒ number
  - .getServerID() ⇒ string
  - .getResponseType()
- ~api() ⇒ Object
  - ~api(key, opts) ⇒ Object
  - ~library([typeOrKey], [id]) ⇒ Object
  - ~items(items) ⇒ Object
  - ~itemTypes() ⇒ Object
  - ~itemFields() ⇒ Object
  - ~creatorFields() ⇒ Object
  - ~schema() ⇒ Object
  - ~fulltextStatus() ⇒ Object
  - ~fulltext() ⇒ Object
  - ~itemTypeFields(itemType) ⇒ Object
  - ~itemTypeCreatorTypes(itemType) ⇒ Object
  - ~template(itemType, subType) ⇒ Object
  - ~collections(collections) ⇒ Object
  - ~subcollections() ⇒ Object
  - ~publications() ⇒ Object
  - ~tags(tags) ⇒ Object
  - ~searches(searches) ⇒ Object
  - ~top() ⇒ Object
  - ~trash() ⇒ Object
  - ~children() ⇒ Object
  - ~settings(settings) ⇒ Object
  - ~deleted(since) ⇒ Object
  - ~groups() ⇒ Object
  - ~version(version) ⇒ Object
  - ~apiVersion(apiVersion) ⇒ Object
  - ~serverID(serverID) ⇒ Object
  - ~attachment([fileName], [file], [mtime], [md5sum], [patch], [algorithm], [zipFilename]) ⇒ Object
  - ~registerAttachment(fileName, fileSize, mtime, md5sum, [zipMD5], [zipFilename]) ⇒ Object
  - ~attachmentUrl() ⇒ Object
  - ~verifyKeyAccess() ⇒ Object
  - ~local() ⇒ Object
  - ~authorize(appName) ⇒ Object
  - ~get(opts) ⇒ Promise
  - ~post(data, opts) ⇒ Promise
  - ~put(data, opts) ⇒ Promise
  - ~patch(data, opts) ⇒ Promise
  - ~del(keysToDelete, opts) ⇒ Promise
  - ~getConfig() ⇒ Object
  - ~pretend(verb, data, opts) ⇒ Promise
  - ~use(extend) ⇒ Object
- ~request(config) ⇒ Promise

zotero-api-client~ApiResponse

Represents a generic Zotero API response. Usually a specialised variant inheriting from this class is returned when doing an API request

Kind: inner class of zotero-api-client

~ApiResponse
- .getResponseType() ⇒ string
- .getData() ⇒ object
- .getLinks() ⇒ object
- .getMeta() ⇒ object
- .getVersion() ⇒ number
- .getServerID() ⇒ string

apiResponse.getResponseType() ⇒ string

Name of the class, useful to determine instance of which specialised class has been returned

Kind: instance method of ApiResponse
Returns: string - name of the class

apiResponse.getData() ⇒ object

Content of the response. Specialised classes provide extracted data depending on context.

Kind: instance method of ApiResponse

apiResponse.getLinks() ⇒ object

Links available in the response. Specialised classes provide extracted links depending on context.

Kind: instance method of ApiResponse

apiResponse.getMeta() ⇒ object

Meta data available in the response. Specialised classes provide extracted meta data depending on context.

Kind: instance method of ApiResponse

apiResponse.getVersion() ⇒ number

Value of the "Last-Modified-Version" header in response if present. Specialised classes provide version depending on context

Kind: instance method of ApiResponse
Returns: number - Version of the content in response

apiResponse.getServerID() ⇒ string

Value of the "Zotero-Server-ID" header in response if present. Identifies the Zotero instance that served the request when using the local API

Kind: instance method of ApiResponse
Returns: string - ID of the Zotero instance that produced the response

zotero-api-client~FullTextStatusResponse ⇐ ApiResponse

Represents a response to a GET request for a library's full-text index status

Kind: inner class of zotero-api-client
Extends: ApiResponse

~FullTextStatusResponse ⇐ ApiResponse
- .getResponseType()
- .getStatus() ⇒ string
- .getIndexedCount() ⇒ number
- .getExpectedCount() ⇒ number

fullTextStatusResponse.getResponseType()

Kind: instance method of FullTextStatusResponse
See: getResponseType

fullTextStatusResponse.getStatus() ⇒ string

Kind: instance method of FullTextStatusResponse
Returns: string - Index status, one of "indexed", "incomplete", "reindexing" or "deindexed"

fullTextStatusResponse.getIndexedCount() ⇒ number

Kind: instance method of FullTextStatusResponse
Returns: number - Number of items currently indexed, or null when not reported (status "indexed"/"deindexed")

fullTextStatusResponse.getExpectedCount() ⇒ number

Kind: instance method of FullTextStatusResponse
Returns: number - Number of items expected to be indexed, or null when not reported (status "indexed"/"deindexed")

zotero-api-client~SingleReadResponse ⇐ ApiResponse

Represents a response to a GET request containing a single entity

Kind: inner class of zotero-api-client
Extends: ApiResponse

~SingleReadResponse ⇐ ApiResponse
- .getResponseType()
- .getData() ⇒ Object

singleReadResponse.getResponseType()

Kind: instance method of SingleReadResponse
See: getResponseType

singleReadResponse.getData() ⇒ Object

Kind: instance method of SingleReadResponse
Returns: Object - entity returned in this response

zotero-api-client~MultiReadResponse ⇐ ApiResponse

represents a response to a GET request containing multiple entities

Kind: inner class of zotero-api-client
Extends: ApiResponse

~MultiReadResponse ⇐ ApiResponse
- .getResponseType()
- .getData() ⇒ Array
- .getLinks() ⇒ Array
- .getMeta() ⇒ Array
- .getTotalResults() ⇒ number
- .getRelLinks() ⇒ object

multiReadResponse.getResponseType()

Kind: instance method of MultiReadResponse
See: getResponseType

multiReadResponse.getData() ⇒ Array

Kind: instance method of MultiReadResponse
Returns: Array - a list of entities returned in this response

multiReadResponse.getLinks() ⇒ Array

Kind: instance method of MultiReadResponse
Returns: Array - a list of links, indexes of the array match indexes of entities in getData

multiReadResponse.getMeta() ⇒ Array

Kind: instance method of MultiReadResponse
Returns: Array - a list of meta-data, indexes of the array match indexes of entities in getData

multiReadResponse.getTotalResults() ⇒ number

Kind: instance method of MultiReadResponse
Returns: number - Total number of results

multiReadResponse.getRelLinks() ⇒ object

Kind: instance method of MultiReadResponse
Returns: object - Parsed content of "Link" header as an object where value of "rel" is a key and the URL is the value. For paginated responses contain URLs for "first", "next", "prev" and "last".

zotero-api-client~SingleWriteResponse ⇐ ApiResponse

Represents a response to a PUT or PATCH request

Kind: inner class of zotero-api-client
Extends: ApiResponse

~SingleWriteResponse ⇐ ApiResponse
- .getResponseType()
- .getData() ⇒ Object

singleWriteResponse.getResponseType()

Kind: instance method of SingleWriteResponse
See: getResponseType

singleWriteResponse.getData() ⇒ Object

Kind: instance method of SingleWriteResponse
Returns: Object - For put requests, this represents a complete, updated object. For patch requests, this represents only updated fields of the updated object.

zotero-api-client~MultiWriteResponse ⇐ ApiResponse

Represents a response to a POST request

Kind: inner class of zotero-api-client
Extends: ApiResponse

~MultiWriteResponse ⇐ ApiResponse
- .getResponseType()
- .isSuccess() ⇒ Boolean
- .getData() ⇒ Array
- .getLinks()
- .getMeta()
- .getErrors() ⇒ Object
- .getEntityByKey(key) ⇒ Object
- .getEntityByIndex(index) ⇒ Object

multiWriteResponse.getResponseType()

Kind: instance method of MultiWriteResponse
See: getResponseType

multiWriteResponse.isSuccess() ⇒ Boolean

Kind: instance method of MultiWriteResponse
Returns: Boolean - Indicates whether all write operations were successful

multiWriteResponse.getData() ⇒ Array

Returns all entities POSTed in an array. Entities that have been written successfully are returned updated, other entities are returned unchanged. It is advised to verify if the request was entirely successful (see isSuccess and getErrors) before using this method.

Kind: instance method of MultiWriteResponse
Returns: Array - A modified list of all entities posted.

multiWriteResponse.getLinks()

Kind: instance method of MultiWriteResponse
See: getLinks

multiWriteResponse.getMeta()

Kind: instance method of MultiWriteResponse
See: getMeta

multiWriteResponse.getErrors() ⇒ Object

Returns all errors that have occurred.

Kind: instance method of MultiWriteResponse
Returns: Object - Errors object where keys are indexes of the array of the original request and values are the errors occurred.

multiWriteResponse.getEntityByKey(key) ⇒ Object

Allows getting an updated entity based on its key, otherwise identical to getEntityByIndex

Kind: instance method of MultiWriteResponse
Throws:

Error If key is not present in the request

See: getEntityByIndex

| Param | Type | | --- | --- | | key | String |

multiWriteResponse.getEntityByIndex(index) ⇒ Object

Allows getting an updated entity based on its index in the original request

Kind: instance method of MultiWriteResponse
Throws:

Error If index is not present in the original request
Error If error occurred in the POST for selected entity. Error message will contain the reason for failure.

| Param | Type | | --- | --- | | index | Number | String |

zotero-api-client~DeleteResponse ⇐ ApiResponse

Represents a response to a DELETE request

Kind: inner class of zotero-api-client
Extends: ApiResponse

deleteResponse.getResponseType()

Kind: instance method of DeleteResponse
See: getResponseType

zotero-api-client~AuthorizeResponse ⇐ ApiResponse

Represents a response to a local API authorization request (POST /api/local/authorize). Local API only

Kind: inner class of zotero-api-client
Extends: ApiResponse

~AuthorizeResponse ⇐ ApiResponse
- .getResponseType()
- .getKey() ⇒ string
- .isRemembered() ⇒ boolean

authorizeResponse.getResponseType()

Kind: instance method of AuthorizeResponse
See: getResponseType

authorizeResponse.getKey() ⇒ string

Local API key granted by the user, to be sent in the "Zotero-API-Key" header on subsequent write requests

Kind: instance method of AuthorizeResponse
Returns: string - Local API key authorizing write requests

authorizeResponse.isRemembered() ⇒ boolean

Whether the user granted persistent access ("Always Allow"). When false, the key is single-use: the first write request that successfully validates it consumes it

Kind: instance method of AuthorizeResponse
Returns: boolean - Whether the key is persistent

zotero-api-client~FileUploadResponse ⇐ ApiResponse

Represents a response to a file upload request

Kind: inner class of zotero-api-client
Extends: ApiResponse
Properties

| Name | Type | Description | | --- | --- | --- | | authResponse | Object | Response object for stage 1 (upload authorisation) request | | response | Object | alias for "authResponse" | | uploadResponse | Object | Response object for stage 2 (file upload) request | | registerResponse | Object | Response object for stage 3 (upload registration) request |

~FileUploadResponse ⇐ ApiResponse
- .getResponseType()
- .getVersion()

fileUploadResponse.getResponseType()

Kind: instance method of FileUploadResponse
See: getResponseType

fileUploadResponse.getVersion()

Kind: instance method of FileUploadResponse
See: getVersion

zotero-api-client~FileDownloadResponse ⇐ ApiResponse

Represents a response to a file download request

Kind: inner class of zotero-api-client
Extends: ApiResponse

fileDownloadResponse.getResponseType()

Kind: instance method of FileDownloadResponse
See: getResponseType

zotero-api-client~FileUrlResponse ⇐ ApiResponse

Represents a response containing temporary url for file download

Kind: inner class of zotero-api-client
Extends: ApiResponse

fileUrlResponse.getResponseType()

Kind: instance method of FileUrlResponse
See: getResponseType

zotero-api-client~RawApiResponse ⇐ ApiResponse

Represents a raw response, e.g. to data requests with format other than JSON

Kind: inner class of zotero-api-client
Extends: ApiResponse

rawApiResponse.getResponseType()

Kind: instance method of RawApiResponse
See: getResponseType

zotero-api-client~PretendResponse ⇐ ApiResponse

Represents a response for pretended request, mostly for debug purposes. See module:zotero-api-client.api~pretend

Kind: inner class of zotero-api-client
Extends: ApiResponse

~PretendResponse ⇐ ApiResponse
- .getResponseType()
- .getVersion() ⇒ Object

pretendResponse.getResponseType()

Kind: instance method of PretendResponse
See: getResponseType

pretendResponse.getVersion() ⇒ Object

Kind: instance method of PretendResponse
Returns: Object - For pretended request version will always be null.

zotero-api-client~ErrorResponse ⇐ Error

Represents an error response from the api

Kind: inner class of zotero-api-client
Extends: Error
Properties

| Name | Type | Description | | --- | --- | --- | | response | Object | Response object for the request, with untouched body | | message | String | What error occurred, usually contains response code and status | | reason | String | More detailed reason for the failure, if provided by the API | | options | Object | Configuration object used for this request |

~ErrorResponse ⇐ Error
- .getVersion() ⇒ number
- .getServerID() ⇒ string
- .getResponseType()

errorResponse.getVersion() ⇒ number

Value of the "Last-Modified-Version" header in response if present. This is generally only available if the server responded with 412 due to a version mismatch.

Kind: instance method of ErrorResponse
Returns: number - Version of the content in response

errorResponse.getServerID() ⇒ string

Value of the "Zotero-Server-ID" header in response if present. Identifies the Zotero instance that served the request when using the local API

Kind: instance method of ErrorResponse
Returns: string - ID of the Zotero instance that produced the response

errorResponse.getResponseType()

Kind: instance method of ErrorResponse
See: getResponseType

zotero-api-client~api() ⇒ Object

Wrapper function creates closure scope and calls api()

Kind: inner method of zotero-api-client
Returns: Object - Partially configured api functions

~api() ⇒ Object
- ~api(key, opts) ⇒ Object
- ~library([typeOrKey], [id]) ⇒ Object
- ~items(items) ⇒ Object
- ~itemTypes() ⇒ Object
- ~itemFields() ⇒ Object
- ~creatorFields() ⇒ Object
- ~schema() ⇒ Object
- ~fulltextStatus() ⇒ Object
- ~fulltext() ⇒ Object
- ~itemTypeFields(itemType) ⇒ Object
- ~itemTypeCreatorTypes(itemType) ⇒ Object
- ~template(itemType, subType) ⇒ Object
- ~collections(collections) ⇒ Object
- ~subcollections() ⇒ Object
- ~publications() ⇒ Object
- ~tags(tags) ⇒ Object
- ~searches(searches) ⇒ Object
- ~top() ⇒ Object
- ~trash() ⇒ Object
- ~children() ⇒ Object
- ~settings(settings) ⇒ Object
- ~deleted(since) ⇒ Object
- ~groups() ⇒ Object
- ~version(version) ⇒ Object
- ~apiVersion(apiVersion) ⇒ Object
- ~serverID(serverID) ⇒ Object
- ~attachment([fileName], [file], [mtime], [md5sum], [patch], [algorithm], [zipFilename]) ⇒ Object
- ~registerAttachment(fileName, fileSize, mtime, md5sum, [zipMD5], [zipFilename]) ⇒ Object
- ~attachmentUrl() ⇒ Object
- ~verifyKeyAccess() ⇒ Object
- ~local() ⇒ Object
- ~authorize(appName) ⇒ Object
- ~get(opts) ⇒ Promise
- ~post(data, opts) ⇒ Promise
- ~put(data, opts) ⇒ Promise
- ~patch(data, opts) ⇒ Promise
- ~del(keysToDelete, opts) ⇒ Promise
- ~getConfig() ⇒ Object
- ~pretend(verb, data, opts) ⇒ Promise
- ~use(extend) ⇒ Object

api~api(key, opts) ⇒ Object

Entry point of the interface. Configures authentication. Can be used to configure any other properties of the api Returns a set of functions that are bound to that configuration and can be called to specify further api configuration.