Zotero API client

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

Small, single purpose module, i.e. talk to the API
Works in both node & browser environment
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

It doesn't do any of the following:

Version management - version headers need to be provided explictely
Caching - each call to get(), post() etc. will actually call the api
Abstraction - There is no Item or Collection objects, only raw JSON

Getting The Library

NPM package contains source of the library which can be used as part of your build (e.g. when using browserify/rollup/webpack etc.) process or directly in node:

npm install zotero-api-client

Also included in the package is an UMD bundle which can be loaded using common loaders or included directly in a <script> tag. In the latter case library will be available as a global scope object ZoteroApiClient. One way of using UMD bundle on your page is to include it from unpkg project CDN:

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

Example

Simple example reading items from the public/test user library.

Import the library, pick one depending on your environment:

// es module, most scenarios when using a bundler:
import api from 'zotero-api-client'
// common-js, node and some cases when using a bundler:
const { default: api } = require('zotero-api-client');
// UMD bundle creates `ZoteroApiClient` global object
const { default: api } = ZoteroApiClient;

Use the api to make the request (we're using async functions)

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

Extract items from the response

const items = response.getData();

Print titles of all the items in the library to console

console.log(items.map(i => i.title));

Overview

Library composes of three layers:

An api function, which is the only interface exported.
A request engine called by the api. It does the heavy lifting. Should not be used directly.
An ApiResponse, which has multiple specialised variants

API interface

API interface is a function that returns set of functions bound to previously configured options. This way it can be chained and stored at any level. Common scenario is to store authentication details and library details, which can be done quite simply:

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

That produces api client already configured with your credentials and user library id. You can re-use it obtain list of collections in that library:

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

Items in that library:

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

Or items in specific collection:

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

There two types of api functions, configuration functions (e.g. items()) that can be further chained and execution functions (e.g. get()) that fire up the request.

For complete reference, please see documentation for api().

Response

Response is an instance of a specialised response class object returned by one of the execution functions of the api. Each response contains a specialised getData() method that will return entities requested or modified, depending on request configuration.

For complete reference, please see documentation SingleReadResponse, MultiReadResponse, SingleWriteResponse, MultiWriteResponse, DeleteResponse, FileUploadResponse, FileDownloadResponse, FileUrlResponse.

Request

Request is a function that takes a complex configuration object generated by the api interface, communicates with the API and returns one of the response objects (see below). Some rarely used properties cannot be configured using api configuration functions and have to be specified as optional properties when calling api() or one of the execution functions of the api.

For a complete list of all the properties request() accepts, please see 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() ⇒ string
  - .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
  - .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(items) ⇒ 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() ⇒ 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`

Contents of "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`

represnets 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() ⇒ string
- .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() ⇒ `string`

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

multiReadResponse.getRelLinks() ⇒ `object`

Kind: instance method of MultiReadResponse
Returns: object - Parsed content of "Link" header as object where value of "rel" is a key and the URL is the value, contains values for "next", "last" etc.

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 reprents 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 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 erorrs occurred.

multiWriteResponse.getEntityByKey(key)

Allows obtaining 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 obtaining 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 occured in the POST for selected entity. Error message will contain reason for failure.

Param	Type
index	`Number`

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 the stage 1 (upload authorisation) request
response	`Object`	alias for "authResponse"
uploadResponse	`Object`	Response object for the stage 2 (file upload) request
registerResponse	`Objext`	Response object for the 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, ususally 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.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(items) ⇒ 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 function that are bound to that configuration and can be called to specify further api configuration.