What is this?

py-clave is a prototype server implementation of a set of public RESTful APIs meant to enable clients to retrieve metadata and contents from a bunch of digital publications in EPUB2 format stored in free-form directory structure.

Written in Python, it is built on the tornado framework, an asynchronous non-blocking web library tuned for high performance and scalability.

How does this work?

The core application in /server.py implements the tornado.web.Application class, with asynchronous handlers for each endpoint. It is meant to be deployed with supervisord process control system, in multiple instances listening to different ports, behind a nginx frontend acting as a reverse proxy. The main process is run on the default 8080 port.

On first run and after a fixed amount of time the server builds a sqlite3 cache of EPUB files stored in the EPUB_FILES_PATH directory (set at startime with the --EPUB_FILES_PATH flag) in order to avoid filesystem traversal on each request. The cache is then updated with a periodic callback invoked with a default interval of 5m, or an interval provided by --DB_UPDATE_TIMEOUT flag.

Wanna know more?

Exhaustive documentation for the implemented HTTP request may be found on the official DOCS. The API is currently designed to differentiate between a GET request coming from a browser reading the Accept: request header, thus showing a descriptive UI rather than raw JSON output. (which is precisely the case, if you're browsing dev.alese.it).