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.
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
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).