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
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>
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));
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 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 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 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().
- zotero-api-client
- ~ApiResponse
- .getResponseType() ⇒
string
- .getData() ⇒
object
- .getLinks() ⇒
object
- .getMeta() ⇒
object
- .getVersion() ⇒
number
- .getResponseType() ⇒
- ~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
- ~FileUploadResponse ⇐
ApiResponse
- ~FileDownloadResponse ⇐
ApiResponse
- ~FileUrlResponse ⇐
ApiResponse
- ~RawApiResponse ⇐
ApiResponse
- ~PretendResponse ⇐
ApiResponse
- .getResponseType()
- .getVersion() ⇒
Object
- ~ErrorResponse ⇐
Error
- .getVersion() ⇒
number
- .getResponseType()
- .getVersion() ⇒
- ~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(key, opts) ⇒
- ~request() ⇒
Object
- ~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
- .getResponseType() ⇒
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
Content of the response. Specialised classes provide extracted data depending on context.
Kind: instance method of ApiResponse
Links available in the response. Specialised classes provide extracted links depending on context.
Kind: instance method of ApiResponse
Meta data available in the response. Specialised classes provide extracted meta data depending on context.
Kind: instance method of ApiResponse
Value 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
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
Kind: instance method of SingleReadResponse
See: getResponseType
Kind: instance method of SingleReadResponse
Returns: Object
- entity returned in this response
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
Kind: instance method of MultiReadResponse
See: getResponseType
Kind: instance method of MultiReadResponse
Returns: Array
- a list of entities returned in this response
Kind: instance method of MultiReadResponse
Returns: Array
- a list of links, indexes of the array match indexes of entities in getData
Kind: instance method of MultiReadResponse
Returns: Array
- a list of meta data, indexes of the array match indexes of entities in getData
Kind: instance method of MultiReadResponse
Returns: string
- Total number of results
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.
Represents a response to a PUT or PATCH request
Kind: inner class of zotero-api-client
Extends: ApiResponse
- ~SingleWriteResponse ⇐
ApiResponse
- .getResponseType()
- .getData() ⇒
Object
Kind: instance method of SingleWriteResponse
See: getResponseType
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.
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
Kind: instance method of MultiWriteResponse
See: getResponseType
Kind: instance method of MultiWriteResponse
Returns: Boolean
- Indicates whether all write operations were successful
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.
Kind: instance method of MultiWriteResponse
See: getLinks
Kind: instance method of MultiWriteResponse
See: getMeta
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.
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 |
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 requestError
If error occured in the POST for selected entity. Error message will contain reason for failure.
Param | Type |
---|---|
index | Number |
Represents a response to a DELETE request
Kind: inner class of zotero-api-client
Extends: ApiResponse
Kind: instance method of DeleteResponse
See: getResponseType
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
Kind: instance method of FileUploadResponse
See: getResponseType
Kind: instance method of FileUploadResponse
See: getVersion
Represents a response to a file download request
Kind: inner class of zotero-api-client
Extends: ApiResponse
Kind: instance method of FileDownloadResponse
See: getResponseType
Represents a response containing temporary url for file download
Kind: inner class of zotero-api-client
Extends: ApiResponse
Kind: instance method of FileUrlResponse
See: getResponseType
Represents a raw response, e.g. to data requests with format other than json
Kind: inner class of zotero-api-client
Extends: ApiResponse
Kind: instance method of RawApiResponse
See: getResponseType
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
Kind: instance method of PretendResponse
See: getResponseType
Kind: instance method of PretendResponse
Returns: Object
- For pretended request version will always be null.
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 ⇐
Error
- .getVersion() ⇒
number
- .getResponseType()
- .getVersion() ⇒
Value of "Last-Modified-Version" header in response if present. This is generally only available if server responded with 412 due to version mismatch.
Kind: instance method of ErrorResponse
Returns: number
- Version of the content in response
Kind: instance method of ErrorResponse
See: getResponseType
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(key, opts) ⇒
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.
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Param | Type | Description |
---|---|---|
key | String |
Authentication key |
opts | Object |
Optional api configuration. For a list of all possible properties, see documentation for request() function |
Configures which library api requests should use.
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Param | Type | Description |
---|---|---|
[typeOrKey] | * |
Library key, e.g. g1234. Alternatively, if second parameter is present, library type i.e either 'group' or 'user' |
[id] | Number |
Only when first argument is a type, library id |
Configures api to use items or a specific item Can be used in conjuction with library(), collections(), top(), trash(), children(), tags() and any execution function (e.g. get(), post())
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Param | Type | Default | Description |
---|---|---|---|
items | String |
|
Item key, if present, configure api to point at this specific item |
Configure api to request all item types Can only be used in conjuction with get()
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Configure api to request all item fields Can only be used in conjuction with get()
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Configure api to request localized creator fields Can only be used in conjuction with get()
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Configure api to request schema Can only be used in conjuction with get()
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Configure api to request all valid fields for an item type Can only be used in conjuction with get()
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Param | Type | Description |
---|---|---|
itemType | String |
item type for which valid fields will be requested, e.g. 'book' or 'journalType' |
Configure api to request valid creator types for an item type Can only be used in conjuction with get()
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Param | Type | Description |
---|---|---|
itemType | String |
item type for which valid creator types will be requested, e.g. 'book' or 'journalType' |
Configure api to request template for a new item Can only be used in conjuction with get()
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Param | Type | Description |
---|---|---|
itemType | String |
item type for which template will be requested, e.g. 'book' or 'journalType' |
subType | String |
annotationType if itemType is 'annotation' or linkMode if itemType is 'attachment' |
Configure api to use collections or a specific collection Can be used in conjuction with library(), items(), top(), tags() and any of the execution function (e.g. get(), post())
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Param | Type | Description |
---|---|---|
items | String |
Collection key, if present, configure api to point to this specific collection |
Configure api to use subcollections that reside underneath the specified collection. Should only be used in conjuction with both library() and collection() and any of the execution function (e.g. get(), post())
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Configure api to narrow the request to only consider items filled under "My Publications" Should only be used in conjuction with both library() and items() and any of the execution function (e.g. get(), post())
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Configure api to request or delete tags or request a specific tag Can be used in conjuction with library(), items(), collections() and any of the following execution functions: get(), delete() but only if the first argument is not present. Otherwise can only be used in conjuctin with get()
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Param | Type | Default | Description |
---|---|---|---|
tags | String |
|
name of a tag to request. If preset, configure api to request specific tag. |
Configure api to use saved searches or a specific saved search Can be used in conjuction with library() and any of the execution functions
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Param | Type | Default | Description |
---|---|---|---|
searches | String |
|
Search key, if present, configure api to point at this specific saved search |
Configure api to narrow the request only to the top level items Can be used in conjuction with items() and collections() and only with conjuction with a get() execution function
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Configure api to narrow the request only to the items in the trash Can be only used in conjuction with items() and get() execution function
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Configure api to narrow the request only to the children of given item Can be only used in conjuction with items() and get() execution function
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Configure api to request settings Can only be used in conjuction with get(), put(), post() and delete() For usage with put() and delete() settings key must be provided For usage with post() settings key must not be included
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Param | Type | Default | Description |
---|---|---|---|
settings | String |
|
Settings key, if present, configure api to point at this specific key within settings, e.g. tagColors . |
Configure api to request deleted content Can only be used in conjuction with get()
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Configure api to request user-accessible groups (i.e. The set of groups the current API key has access to, including public groups the key owner belongs to even if the key doesn't have explicit permissions for them.) Can only be used in conjuction with get()
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Configure api to specify local version of given entity. When used in conjuction with get() exec function, it will populate the If-Modified-Since-Version header. When used in conjuction with post(), put(), patch() or delete() it will populate the If-Unmodified-Since-Version header.
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Param | Type | Description |
---|---|---|
version | Number |
local version of the entity |
Configure api to upload or download an attachment file.
Can be only used in conjuction with items() and post()/get()/patch().
Method patch() can only be used to upload a binary patch, in this case last two argument
must be provided.
Method post() is used for full uploads. If md5sum
is provided, it will update existing
file, otherwise it uploads a new file. Last two arguments are not used in this scenario.
Method get() is used for downloads, in this case skip all arguments.
Use items() to select attachment item for which file is uploaded/downloaded.
Will populate format on download as well as Content-Type, If*Match headers in case of upload.
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Param | Type | Description |
---|---|---|
[fileName] | String |
For upload: name of the file, should match values in attachment item entry |
[file] | ArrayBuffer |
New file to be uploaded |
[mtime] | Number |
New file's mtime, leave empty to assume current date/time |
[md5sum] | String |
MD5 hash of an existing file, required for uploads that update existing file |
patch | ArrayBuffer |
Binary patch, to be applied to the old file, to produce a new file |
[algorithm] | String |
Algorithm used to compute a diff: xdelta, vcdiff or bsdiff |
Advanced function that will attempt to register existing file with given attachment-item based on known file metadata. Can be only used in conjuction with items() and post(). Use items() to select attachment item for which file is registered. Will populate Content-Type, If-Match headers. Will fail with a ErrorResponse if API does not return "exists".
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Param | Type | Description |
---|---|---|
fileName | String |
name of the file, should match values in attachment item entry |
fileSize | Number |
size of the existing file |
mtime | Number |
mtime of the existing file |
md5sum | String |
md5sum of the existing file |
Configure api to request a temporary attachment file url Can be only used in conjuction with items() and get() Use items() to select attachment item for which file is url is requested Will populate format, redirect
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Configure api to request information on the API key. Can only be used in conjuction with get()
Kind: inner method of api
Chainable
Returns: Object
- Partially configured api functions
Execution function. Specifies that the request should use a GET method.
Kind: inner method of api
Returns: Promise
- A promise that will eventually return either an
ApiResponse, SingleReadResponse or MultiReadResponse.
Might throw Error or ErrorResponse.
Param | Type | Description |
---|---|---|
opts | Object |
Optional api configuration. If duplicate, overrides properties already present. For a list of all possible properties, see documentation for request() function |
Execution function. Specifies that the request should use a POST method.
Kind: inner method of api
Returns: Promise
- A promise that will eventually return MultiWriteResponse.
Might throw Error or ErrorResponse
Param | Type | Description |
---|---|---|
data | Array |
An array of entities to post |
opts | Object |
Optional api configuration. If duplicate, overrides properties already present. For a list of all possible properties, see documentation for request() function |
Execution function. Specifies that the request should use a PUT method.
Kind: inner method of api
Returns: Promise
- A promise that will eventually return SingleWriteResponse.
Might throw Error or ErrorResponse
Param | Type | Description |
---|---|---|
data | Object |
An entity to put |
opts | Object |
Optional api configuration. If duplicate, overrides properties already present. For a list of all possible properties, see documentation for request() function |
Execution function. Specifies that the request should use a PATCH method.
Kind: inner method of api
Returns: Promise
- A promise that will eventually return SingleWriteResponse.
Might throw Error or ErrorResponse
Param | Type | Description |
---|---|---|
data | Object |
Partial entity data to patch |
opts | Object |
Optional api configuration. If duplicate, overrides properties already present. For a list of all possible properties, see documentation for request() function |
Execution function. Specifies that the request should use a DELETE method.
Kind: inner method of api
Returns: Promise
- A promise that will eventually return DeleteResponse.
Might throw Error or ErrorResponse
Param | Type | Description |
---|---|---|
keysToDelete | Array |
An array of keys to delete. Depending on how api has been configured, these will be item keys, collection keys, search keys or tag names. If not present, api should be configured to use specific item, collection, saved search or settings key, in which case, that entity will be deleted |
opts | Object |
Optional api configuration. If duplicate, overrides properties already present. For a list of all possible properties, see documentation for request() function |
Execution function. Returns current config without doing any requests. Usually used in advanced scenarios where config needs to be tweaked manually before submitted to the request method or as a debugging tool.
Kind: inner method of api
Returns: Object
- current config
Execution function. Prepares the request but does not execute fetch() instead returning a "pretended" response where details for the actual fetch that would have been used are included. Usually used in advanced scenarios where config needs to be tweaked manually before it is submitted to the request method or as a debugging tool.
Kind: inner method of api
Returns: Promise
- A promise that will eventually return PretendResponse.
Might throw Error or ErrorResponse
Param | Type | Default | Description |
---|---|---|---|
verb | String |
get |
Defines which execution function is used to prepare the request. Should be one of 'get', 'post', 'patch' 'put', 'delete'. Defaults to 'get'. |
data | Object |
This argument is passed over to the actual execution function. For 'get' it is ignored, for 'post', 'patch' and 'put' see 'data' of that execution function, for 'delete' see 'keysToDelete' | |
opts | Object |
Optional api configuration. If duplicate, overrides properties already present. For a list of all possible properties, see documentation for request() function |
Used for extending capabilities of the library by installing plugins. In most cases plugins inject additional executors or bind api to an alternative/extended set of functions
Kind: inner method of api
Returns: Object
- Extended/partially configured api functions
Param | Type | Description |
---|---|---|
extend | function |
function that installs alternative or additional functionality of the api. It should return bound api functions, usually by caling arguments[0].ef() |
Executes request and returns a response. Not meant to be called directly, instead use api.
Kind: inner method of zotero-api-client
Returns: Object
- Returns a Promise that will eventually return a response object
Throws:
Error
If options specify impossible configurationErrorResponse
If API responds with a non-ok response
Param | Type | Description |
---|---|---|
options.apiScheme | String |
Scheme part of the API URL |
options.apiAuthorityPart | String |
Authority part of the API URL |
options.apiPath | String |
Path part of the API URL |
options.authorization | String |
'Authorization' header |
options.zoteroWriteToken | String |
'Zotero-Write-Token' header |
options.ifModifiedSinceVersion | String |
'If-Modified-Since-Version' header |
options.ifUnmodifiedSinceVersion | String |
'If-Unmodified-Since-Version' header |
options.contentType | String |
'Content-Type' header |
options.collectionKey | String |
'collectionKey' query argument |
options.content | String |
'content' query argument |
options.direction | String |
'direction' query argument |
options.format | String |
'format' query argument |
options.include | String |
'include' query argument |
options.includeTrashed | String |
'includeTrashed' query argument |
options.itemKey | String |
'itemKey' query argument |
options.itemQ | String |
'itemQ' query argument |
options.itemQMode | String |
'itemQMode' query argument |
options.itemTag | String | Array.<String> |
'itemTag' query argument |
options.itemType | String |
'itemType' query argument |
options.limit | Number |
'limit' query argument |
options.linkMode | String |
'linkMode' query argument |
options.locale | String |
'locale' query argument |
options.q | String |
'q' query argument |
options.qmode | String |
'qmode' query argument |
options.searchKey | String |
'searchKey' query argument |
options.since | Number |
'since' query argument |
options.sort | String |
'sort' query argument |
options.start | Number |
'start' query argument |
options.style | String |
'style' query argument |
options.tag | String | Array.<String> |
'tag' query argument |
options.pretend | Boolean |
triggers pretend mode where fetch request is prepared and returned without execution |
options.resource.top | String |
use 'top' resource |
options.resource.trash | String |
use 'trash' resource |
options.resource.children | String |
use 'children' resource |
options.resource.groups | String |
use 'groups' resource |
options.resource.itemTypes | String |
use 'itemTypes' resource |
options.resource.itemFields | String |
use 'itemFields' resource |
options.resource.creatorFields | String |
use 'creatorFields' resource |
options.resource.itemTypeFields | String |
use 'itemTypeFields' resource |
options.resource.itemTypeCreatorTypes | String |
use 'itemTypeCreatorTypes' resource |
options.resource.library | String |
use 'library' resource |
options.resource.collections | String |
use 'collections' resource |
options.resource.items | String |
use 'items' resource |
options.resource.searches | String |
use 'searches' resource |
options.resource.tags | String |
use 'tags' resource |
options.resource.template | String |
use 'template' resource |
options.method | String |
forwarded to fetch() |
options.body | String |
forwarded to fetch() |
options.mode | String |
forwarded to fetch() |
options.cache | String |
forwarded to fetch() |
options.credentials | String |
forwarded to fetch() |
options.uploadRegisterOnly | Boolean |
this file upload should only perform stage 1 error if file with provided meta does not exist |
options.retry | Number |
retry this many times after transient error. |
options.retryDelay | Number |
wait this many seconds before retry. If not set an exponential backoff algorithm will be used |