/dev/docs/coverthing
Type: /type/page
body: value: <style>
pre {
	background-color:#F0F0F0;
	border:1px solid #CCCBBA;
       padding: 10px 10px 10px 20px;
}

code {
    background: inherit;
    color: inherit;
}

h3 {
    text-transform: inherit;
}

</style>

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?
title: Coverthing