Awesome

ZotServer for Zotero

ZotServer provides locally accessible HTTP API. This is a convenient way to integrate Zotero with other desktop applications that require access to its database.

My motivation for development of this addon is to connect my note-taking software to Zotero database without active internet connection. I am working on a connector that will allow me to quickly search and link to Zotero items right from the text editor.

Installation

Download lastest stable version of the addon from GitHub release page of this repository
Use "Install addon from file" menu link in Zotero and select the downloaded .xpi file

How to find "Install addon from file" option:

Go to "Tools" menu, click on "Add-ons" option

Click on a cog icon on top right corner

There now should be "Install Add-on From File" option

Alternatives

Zotero already provides a couple of ways to access its database:

Direct access to SQLite database
Web API of Zotero Storage service
zotero-api-endpoint plugin team is working on the similar functionality

ZotServer addon provides a third way with local-only HTTP API that uses JavaSceript API internally.

Implementation

Zotero is already coming with an HTTP server implementation that runs on port 23119. It serves browser connector endpoints to add new items to Zotero database.

ZotServer relies on the original implementation of the server and augments it with new endpoints to serve functionality like database search

Endpoint Security

Please see discussion for more information.

Documentation

Search

POST /zotserver/search

A search endpoint that expects POST request with JSON body that describes search conditions.

Example JSON body:

[
    {
        "condition": "quicksearch-everything",
        "value": "Ahrens"
    },
    {
        "condition": "tag",
        "operator": "is",
        "value": "productivity"
        "required": true
    }
]

JSON body contains an array of search conditions. Each search condition can have following fields:

Field	Required	Defaults To
`condition`	Yes	None
`operator`	No	`contains`
`value`	Yes	None
`required`	No	`false`

Following conditions are accepted:

Condition	Description	Default Operator
`quicksearch-everything`	Search on all item fields, similar to search field in Zotero UI	`contains`
`quicksearch-titleCreatorYear`	Search on title, creator and year fields	`contains`
`tag`	Search on a particular tag	None

Some more conditions are described here: Zotero JavaScript API on search

Roadmap

Current roadmap is basically based on the idea of parity with functionality of Zotero Storage.

Contributing

ZotServer is written with TypeScript and main source code is located under src directory.

I am assuming that the majority of contributions will be dealing with existing or new endpoints. Below is an overview of endpoints structure.

All endpoint code should be placed in src/endpoints directory in a file named after the class it contains.

A simple template for such file is below:

import EndpointInterface from '../types/EndpointInterface';

export default class Collections implements EndpointInterface {
    supportedMethods = ['GET','POST','PUT','DELETE'];
    supportedDataTypes = ['application/json'];
    permitBookmarklet = false;

    public async init(request: any) {
        return [200, 'application/json', JSON.stringify('response data')];
    }
}

init is the main method that should return a response array in specified format: [<http response code>, <response content type>, <response body>].

Example request object (for search endpoint in this particular case):

{
    "method": "POST",
    "pathname": "/zotserver/search",
    "query": {},
    "headers": {
        "Content-Type": "application/json",
        "User-Agent": "browser",
        "Accept": "*/*",
        "Cache-Control": "no-cache",
        "Host": "localhost:23119",
        "Accept-Encoding": "gzip, deflate, br",
        "Connection": "keep-alive",
        "Content-Length": "89"
    },
    "data": [
        { "condition": "quicksearch-everything", "value": "Ahrens"}
    ]
}

You will then need to register this new endpoint in zotserver.ts file and assing it unique url path.

Endpoints implementation relies on Zotero JavaScript API.

For more information on addon development workflow please refer to Zotero Plugin Development page.

Here is my command to run Zotero in development mode that you might find useful:

/Applications/Zotero.app/Contents/MacOS/zotero -p <your-development-profile-name> -ZoteroDebugText -jsconsole -purgecache

For questions or help requests please join Gitter room: https://gitter.im/ZotServer/community

Your contributions are highly appreciated!