Skip to content

e-zz/ZotServer

 
 

Repository files navigation

Modification

To interact with Logseq, for now I added src/endpoints/Selected.ts. By implementing the endpoints needed, one can possibly enable features like two-way notes syncing, PDF search and import, citation management and so on.

Credits to cboulanger/excite-docker for useful examples.

Original readme:

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

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

How to find "Install addon from file" option:

  1. Go to "Tools" menu, click on "Add-ons" option
  2. Click on a cog icon on top right corner
  3. There now should be "Install Add-on From File" option

Alternatives

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

  1. Direct access to SQLite database
  2. Web API of Zotero Storage service
  3. 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!

License

License: AGPL v3

About

Zotero Local HTTP Server

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages

  • TypeScript 92.3%
  • Makefile 7.7%