Blog About About Threepress Help

Library

Sign in

About the Bookworm API

The Bookworm API (or Application Programming Interface) allows users and developers to access many of the features of Bookworm from other applications. Using the API, a developer can add, download, and list the EPUB content over HTTP in a user's Library. This page describes the API in fairly low-level detail. This (rather dry) description is intented only for developers.

Authorization

You need to sign up for Bookworm before using the API, as access is limited to existing users. After logging in, visit your Profile to find your api_key. This api_key is a required parameter for all API requests and each request will be authorized against the api_key.

Keep your API key private, like a password. Your API key will change if you update your password.

The API is only available over HTTPS.

Library listing

An API client may request the list of titles in their Library using an authorized HTTP GET. The results will be returned as an XHTML page that includes every title in one ordered list. Each list item will include a hyperlink to a document address, the Title, Author(s), and Date added. The list will be ordered by Date added. The list will not be paginated. Here's a sample: 

$ curl -ik "https://bookworm_api_test/api/documents/?api_key=your_api_key_here"

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
...

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" ></meta>    
    <title>Bookworm API title list</title>
  </head>
  <body>
    <div id="content">
  
  <!-- Document list -->
    <ol>
      
      <li> 
        <span class="document-title">Painting the Web</span>
        <span class="document-authors">Shelley Powers</span>
        <span class="document-date-added">2008-07-10 16:17:56</span>
        <span class="document-address">
          <a href="https://bookworm_api_test/api/documents/8/">
            https://bookworm_api_test/api/documents/8/</a></span>
        <!-- Painting the Web by Shelley Powers (book.epub) -->
      </li>
      
      <li> 
        <span class="document-title">iPhone: The Missing Manual</span>
        <span class="document-authors">David Pogue</span>
        <span class="document-date-added">2008-07-31 10:34:49</span>
        <span class="document-address">
          <a href="https://bookworm_api_test/api/documents/97/">
            https://bookworm_api_test/api/documents/97/</a></span>
        <!-- iPhone: The Missing Manual by David Pogue (9780596153960.epub) -->
      </li>
      <li> 
        <span class="document-title">The Way We live Now</span>
        <span class="document-authors">Anthony Trollope</span>
        <span class="document-date-added">2009-03-30 12:36:04</span>
        <span class="document-address">
          <a href="https://bookworm_api_test/api/documents/15215/">
            https://bookworm_api_test/api/documents/15215/</a></span>
        <!-- The Way We live Now by Anthony Trollope (Penguin_Trollope_WayWeLiveNow.epub) -->
      </li>
      
      <li> 
        <span class="document-title">The Twitter Book</span>
        <span class="document-authors">Tim O'Reilly, Sarah Milstein</span>
        <span class="document-date-added">2009-04-27 09:21:42</span>
        <span class="document-address">
          <a href="https://bookworm_api_test/api/documents/20258/">
            https://bookworm_api_test/api/documents/20258/</a></span>
        <!-- The Twitter Book by Tim O'Reilly... (conv_house_source.epub) -->
      </li>
      
      <li> 
        <span class="document-title">Unit Test: stamp.001</span>
        <span class="document-authors">Norman Walsh</span>
        <span class="document-date-added">2009-05-01 23:43:59</span>
        <span class="document-address">
          <a href="https://bookworm_api_test/api/documents/20941/">
            https://bookworm_api_test/api/documents/20941/</a></span>
        <!-- Unit Test: stamp.001 by Norman Walsh (sample.epub) -->
      </li>
      
    </ol>

    </div>
  </body>
</html>

The listing like the above is available via an authorized HTTP GET from /api/documents/.

Adding titles to your Library

A new title in EPUB format may be added to your Library using an authorized HTTP POST using either of two techniques: directly via EPUB upload or indirectly by EPUB URL reference.

If using direct EPUB upload, the API user will POST a file's contents as multipart/form-data using the parameter epub_data for the EPUB bytes to /api/documents/ (remember your api_key too). Here's an example of this using curl: 

#!/bin/bash

# Example Bookworm API client implementation to upload a file test.epub
# using curl.  This script expects two arguments: the Bookworm 
# installation URL and a valid API key.
#
# curl must be installed (surprise).
# The Bookworm URL should have no trailing slash (e.g.
# https://bookworm.oreilly.com)

BW=$1
KEY=$2

# Upload a document
curl -iF epub_data=@test.epub -F api_key=$KEY $1/api/documents/ -D result.txt

If you'd prefer to add a new ePub by URL reference, POST a request to /api/documents/ with an epub_url parameter that references an externally-hosted ePub document available by unauthenticated HTTP GET. The Bookworm server will initiate a request for this ePub document and proceed as normal (maybe).

If either upload technique described above succeeds and the new ePub content is accepted by the Bookworm server, an HTTP 201 Created response (probably following some HTTP 100 Continues) will be returned and the Content-Location header will reference the document address (write that down). The newly-uploaded title will now be available in the user's Library .

Neither method for adding new ePubs checks to see if the user already seems to have this title in their Library . API clients should check the contents of the user's Library listing before adding new titles.

Downloading ePub content from your Library

API users will be able to download complete ePub documents from the user's Library by document address. An authorized HTTP GET of a document address will return the complete content as application/epub+zip.