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. API response is returned with a minimal layer to automate common tasks and offers unrestricted access to the response raw 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 library 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: 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().

API Reference

zotero-api-client
- ~ApiResponse
  - .getResponseType() ⇒ string
  - .getData() ⇒ object
  - .getLinks() ⇒ object
  - .getMeta() ⇒ object
  - .getVersion() ⇒ 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)
  - .getEntityByIndex(index) ⇒ Object
- ~DeleteResponse ⇐ ApiResponse
  - .getResponseType()
- ~FileUploadResponse ⇐ ApiResponse
  - .getResponseType()
  - .getVersion()
- ~FileDownloadResponse ⇐ ApiResponse
  - .getResponseType()
- ~FileUrlResponse ⇐ ApiResponse
  - .getResponseType()
- ~RawApiResponse ⇐ ApiResponse
  - .getResponseType()
- ~PretendResponse ⇐ ApiResponse
  - .getResponseType()
  - .getVersion() ⇒ Object
- ~ErrorResponse ⇐ Error
  - .getVersion() ⇒ number
  - .getResponseType()
- ~api() ⇒ Object
  - ~api(key, opts) ⇒ Object
  - ~library([typeOrKey], [id]) ⇒ Object
  - ~items(items) ⇒ Object
  - ~itemTypes() ⇒ Object
  - ~itemFields() ⇒ Object
  - ~creatorFields() ⇒ Object
  - ~schema() ⇒ 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() ⇒ Object
  - ~groups() ⇒ Object
  - ~version(version) ⇒ Object
  - ~attachment([fileName], [file], [mtime], [md5sum], patch, [algorithm]) ⇒ Object
  - ~registerAttachment(fileName, fileSize, mtime, md5sum) ⇒ Object
  - ~attachmentUrl() ⇒ Object
  - ~verifyKeyAccess() ⇒ 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) ⇒ Object

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

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

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)
- .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 getError) 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)

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: module:zotero-api-client.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~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	`String`	Configuration object used for this request

~ErrorResponse ⇐ Error
- .getVersion() ⇒ number
- .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.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
- ~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() ⇒ Object
- ~groups() ⇒ Object
- ~version(version) ⇒ Object
- ~attachment([fileName], [file], [mtime], [md5sum], patch, [algorithm]) ⇒ Object
- ~registerAttachment(fileName, fileSize, mtime, md5sum) ⇒ Object
- ~attachmentUrl() ⇒ Object
- ~verifyKeyAccess() ⇒ 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.