Coverthing

This is a proposal to build coverthing, an open repository of book covers.
It is a website, where anyone can upload an image of a book cover or request a cover that we have, associate metadata with a cover image which can be queried later.

Coverthing contains many cover images and one or more records for each image. All these records and images are world-readable.

Each record belongs to a collection and each collection will be owned by some user. Any record can be modified by the owner of the collection it belongs to. Records that do not belong to any collection are treated as unnamed collection.

Since it gives complete control over the records in a collection, it encourages people to use coverthing instead of a private collection for managing their book covers.

API

Get

Get image for a record id. The following image sizes are available.

thumbnail   75x75
small       110x110
medium      160x160
large       500x500
original    uploaded size

(Tentative image sizes. These may change in future.)

Example

http://covers.openlibary.org/api/get/1234/small.jpg
http://covers.openlibary.org/api/get/1234/thumbnail.jpg

Upload

Upload a new image and create a new record for it.

Send a post request to the following URL:

http://covers.openlibrary.org/api/upload

Arguments

• image - image data
  
• arbitrary key value pairs.

Errors

• Filesize was zero
  
• Filetype was not recognised

Example Response

{'status': 'ok', 'id': '1234'}

New Record

Creates a new record for an existing image.

Send a POST request to the following URL.

http://covers.openlibrary.org/api/new_record

Arguments

• base_record: use image from this record
  
• additional key value pairs

Errors

• Invalid record id

Example Response

{'status': 'ok', 'id': '1234'}

Update

Update an existing record.

Send a POST request to the following URL.

http://covers.openlibrary.org/api/update

Arguments

• id
  
• any key-value pairs

Query

query the database for matching records.

Send a GET request to the following URL:

http://covers.openlibrary.org/api/query

Arguments

any key value pairs.

Example

The following query finds all records which have isbn=1234 and returns the ids of the matching records in sorted order of priority.

http://covers.openlibrary.org/api/query?isbn=1234&sort=priority

Example Response

{'status': 'ok', 'result': ['1', '34', '54']}

Suggest

Search the database for nearly matching records.

Send a GET request to the following URL:

http://covers.openlibrary.org/api/suggest

Arguments

any key value pairs.

Example

The following query finds all records which have either isbn="1234567890" or title="The Adventures of Tom Sawyer".

http://covers.openlibrary.org/api/query?isbn=1234567890&title=The+Adventures+of+Tom+Sawyer

Example Response

{'status': 'ok', 'result': ['1', '34', '54']}

Open Issues

User authentication

* How to provide user authentication? use API KEY?
* It should be possible to upload images to coverthing directly from the browser without exposing the credentials

Extending coverthing to author photographs

We need to specify a parameter to distinguish between book covers and author photos. Here are the available options.

1. new subdomain. Same API can be used.

   • http://covers.openlibrary.org/api/get/1234/small.jpg
   • http://authors.openlibrary.org/api/get/1234/small.jpg

2. new dir

   • http://covers.openlibrary.org/bookcovers/api/get/1234/small.jpg
   • http://covers.openlibrary.org/authors/api/get/1234/small.jpg

3. as a query string (ugly)

   • http://covers.openlibrary.org/api/get/1234/small.jpg?category=bookcovers

Option#2 looks like the best option.

We can extend this to store even OL static images by defining a new category.

Any suggestions for a better name?

Any suggestions for a better name?

How about calling it http://media.openlibrary.org or http://static.openlibrary.org?

can we get rid of api in the URL?
How about just /bookcovers/get or /bookcovers/upload?

Shortcut API for search+get?

How about providing quick image search based on one condition which returns the first image from the results?
For example, find the image of the book with isbn=1234567890.

http://covers.openlibrary.org/api/get/isbn/1234567890/small.jpg

If no such image is found, it should return a default image.

/api/get is already used for returning images based on record id. Will be better is use the same for this purpose also or use a different name?