/dev/docs/restful_api
Type: /type/page
body: value: <style type="text/css">
pre { background-color:#F0F0F0; border:1px solid #CCCBBA; padding: 10px 10px 10px 20px; }
</style>

Open Library provides a RESTful API for accessing resources in multiple formats.

<ul>
  <li><a href="#content">Content</a></li>
  <li><a href="#query">Query</a></li>
  <li><a href="#history">History</a></li>
  <li><a href="#recent_changes">Recent Changes</a></li>
  <li><a href="#login">Login</a></li>
  <li><a href="#save">Save</a></li>
  <li><a href="#status_codes">Status Codes</a></li>
</ul>

<a name="content">&nbsp;</a>
## Content

To request any content, the requested format can be specified using `Accept:` header or as part of the URL.
The currently available formats are JSON and RDF.

    $ curl http://openlibrary.org/authors/OL1A.json
    {
        "name": "Sachi Rautroy", 
        ...
    }
    $ curl -s -H 'Accept: application/json' https://openlibrary.org/books/OL1M
    {
        "name": "Sachi Rautroy", 
        ...
    }
    
Optional `callback` parameter can be specified when the requested format is JSON.

    $ curl http://openlibrary.org/authors/OL1A.json?callback=process
    process({
        "name": "Sachi Rautroy", 
        ...
    });
    
The RDF format is available for books and for authors.

    $ curl https://openlibrary.org/books/OL6807502M.rdf
    <rdf:Description rdf:about="http://openlibrary.org/books/OL6807502M">
    <!-- authors -->
    <bibo:authorList rdf:parseType="Collection">
      <rdf:Description rdf:about="http://openlibrary.org/authors/OL1518080A">
         <rdf:value>Lawrence Lessig</rdf:value>
      </rdf:Description>
    </bibo:authorList>
        <!-- bibliographic description -->
        <dcterms:title>Code and other laws of cyberspace</dcterms:title>
        <dcterms:publisher>Basic Books</dcterms:publisher>
        <rdvocab:placeOfPublication>New York</rdvocab:placeOfPublication>
        <dcterms:issued>1999</dcterms:issued>
        <dcterms:extent>xii, 297 p. :</dcterms:extent>
       ....
    </rdf:RDF>
    $ curl -H 'Accept: application/rdf+xml' https://openlibrary.org/books/OL6807502M.rdf
    <rdf:Description rdf:about="http://openlibrary.org/books/OL6807502M">
    <!-- authors -->
    <bibo:authorList rdf:parseType="Collection">
      <rdf:Description rdf:about="http://openlibrary.org/authors/OL1518080A">
         <rdf:value>Lawrence Lessig</rdf:value>
      </rdf:Description>
    </bibo:authorList>
       <!-- bibliographic description -->
        <dcterms:title>Code and other laws of cyberspace</dcterms:title>
    </rdf:RDF>

Open Library also allows accessing editions of a work and works of an author using a simple URL format.

    $ curl 'http://openlibrary.org/works/OL27258W/editions.json?limit=5'
    {
        "size": 19,
        "links": {
            "self": "/works/OL27258W/editions.json?limit=5",
            "work": "/works/OL27258W",
            "next": "/works/OL27258W/editions.json?limit=5&offset=5"
        }, 
        "entries": [{
            "key": "/books/OL17987798M",
            "title": "Neuromantiker",
            ...
        }, ...]
    }

    $ curl http://openlibrary.org/authors/OL1A/works.json
    {
        "size": 16,
        "links": {
            "self": "/authors/OL1A/works.json", 
            "author": "/authors/OL1A"}
        },
        "entries": [{
            "key": "/works/OL14930760W",
            "title": "Satchidananda Raut Roy",
            ...
        }, ...]
    }
    
<a name="query">&nbsp;</a>
## Query

The Query API allows querying the Open Library system for matching objects. 

    $ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A'
    [
        {
            "key": "/books/OL1M"
        }, 
        {
            "key": "/books/OL4731M"
        }, 
        ...
    ]
    $ curl -H 'Accept: application/json' 'https://openlibrary.org/query?type=/type/edition&authors=/authors/OL1A'
    [
        {
            "key": "/books/OL1M"
        }, 
        {
            "key": "/books/OL4731M"
        }, 
        ...
    ]    
    $ curl 'http://openlibrary.org/query.json?type=/type/edition&works=/works/OL2040129W'
    [
        {
            "key": "/books/OL9770407M"
        },
        {
            "key": "/books/OL21857767M"
        },
        ...
    ]    

Additional properties of each object can be requested by passing a query parameter with empty value.

    $ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&title='
    [
        {
            "key": "/books/OL1M", 
            "title": "Kabit\u0101."
        }, 
        {
            "key": "/books/OL4731M", 
            "title": "Sacci Ra\u0304utara\u0304y\u0307a grantha\u0304bal\u0323i\u0304."
        }, 
        ...
    ]

All properties can be requested using a special query parameter `*`.

    $ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&*='
    [
        {
            "pagination": "8, 304 p.", 
            ...
            "title": "Kabit\u0101.", 
            ...
            "key": "/books/OL1M", 
            ...
        },
        ...
    ]

Optional `limit` and `offset` parameters can be passed to limit the number of requests and offset in the results respectively. Unless any limit is specified, the responses is limited to 20 entries. Maximum allowed value of `limit` is 1000 due to performance reasons.

    $ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&limit=2'
    [
        {
            "key": "/books/OL1M"
        }, 
        {
            "key": "/books/OL4731M"
        }
    ]

Queries can also be specified by passing the query as JSON dictionary. The above mentioned approach is just a syntactic-sugar for this.

    # curl fails because it doesn't escape query parameter
    $ wget -q -O - 'http://openlibrary.org/query.json?query={"type": "/type/edition", "authors": "/authors/OL1A", "title": null, "limit": 2}'
    [
        {
            "key": "/books/OL1M", 
            "title": "Kabit\u0101."
        }, 
        {
            "key": "/books/OL4731M", 
            "title": "Sacci Ra\u0304utara\u0304y\u0307a grantha\u0304bal\u0323i\u0304."
        }
    ]

*Please note that this API should not be used for bulk downloads.* [[/developers/dumps|Dumps of all data]] are provided at regular intervals and they should be used for bulk access.

<a name="history">&nbsp;</a>
## History

Change history of any object can be accessed by passing `?m=history` query parameter to the resource url.

    $ curl http://openlibrary.org/books/OL1M.json?m=history
    [
        {
            "comment": "test", 
            "created": "2008-10-14T08:58:48.091739", 
            ...
        },
        ...
    ]
    $ curl -H 'Accept: application/json' https://openlibrary.org/books/OL1M?m=history
    [
        {
            "comment": "test", 
            "created": "2008-10-14T08:58:48.091739", 
            ...
        },
        ...
    ]
    

The entries are sorted in the descending order of created time. 
The number of entries are limited to 20 by default and a different limit can be specified by passing `limit` parameters. 
Optional `offset` parameter can also be specified to get results starting from an offset.
Maximum allowed value of `limit` is 1000 due to performance reasons.

    $ curl http://openlibrary.org/books/OL1M.json?m=history&limit=2&offset=1
    [
        {
            "comment": "test table of contents", 
            "created": "2008-10-13T06:46:27.278809", 
            ...
        },
        {
            "comment": "test", 
            "created": "2008-09-12T14:37:30.974510", 
            ...
        }
    ]
    
Support for RSS and Atom formats will be available soon.

<a name="recent_changes">&nbsp;</a>
## Recent Changes

Recent changes is available in JSON, RSS and Atom formats.

    $ curl http://openlibrary.org/recentchanges.json
    [
        {
            "comment": "new author", 
            ...
        },
        ...
    ]
    $ curl -H 'Accept: application/json' https://openlibrary.org/recentchanges
    [
        {
            "comment": "new author", 
            ...
        },
        ...
    ]
    
Parameters, `type`, `key` and `author` can be specified to limit the results to modifications to objects of specified type, specified key and by an author respectively. Also `limit` and `offset` can be specified to limit number of results and offset.

    $ curl http://openlibrary.org/recentchanges.json?type=/type/page
    ...
    $ curl http://openlibrary.org/recentchanges.json?author=/people/anand&offset=20&limit=20

Support for RSS and Atom formats will be available soon.

<a name="login">&nbsp;</a>
## Login

To login to Open Library programatically, a POST request must be send to `/account/login.json` with your S3 `access` and `secret` keys passed as a JSON dictionary. 

    $ curl -i -H 'Content-Type: application/json' -d '{"access": "your access key", "secret": "your secret key"}' https://openlibrary.org/account/login
    HTTP/1.1 200 OK
    Set-Cookie: session="/user/username%2C2009-02-19T07%3A52%3A13%2C74fc6%24811f4c2e5cf52ed0ef83b680ebed861f"; Path=/
    
Upon successful login, a set-cookie header is returned in the response. Include this cookie with subsequent requests.

Every Open Library account holder has S3 keys. You can find yours <a href="https://archive.org/account/s3.php">here</a>.

<a name="save">&nbsp;</a>
## Save

Modifying objects can be done by sending a PUT request to the resource url with appropriate `Content-Type` header. The currently supported format is only JSON.

    TODO: show an example
    
Please note that right now this only an internal API and works only from the localhost.

<a name="status_codes">&nbsp;</a>
## Status codes

### 200 OK

Status code `200 OK` is returned when the request is handled successfully.

### 400 Bad Request

Status code `400 Bad Request` is returned when there is any error in the provided input data.
The error message is specified in the response body.

### 403 Forbidden

Status code `403 Forbidden` is returned for PUT/POST requests when the requesting user does not have the required permissions to modify the resource.

The request can be repeated by providing the required credentials.

### 404 Not Found

Status code `404 Not Found` is returned when the requested resource is not found.

### 500 Internal Server Error

Status code `500 Internal Server Error` is returned if handling the request causes any internal errors.
Debug information about the error may be provided in the response to help trouble-shooting the issue.
title: Open Library RESTful API
m: edit