Upcoming Lists API

This is a draft of upcoming lists API. This is still under development.

Get Lists of a user

Request:

GET http://openlibrary.org/people/george08/lists.json

Response:

{
    "links": {
        "self": "/people/george08/lists.json",
        "next": "/people/george08/lists.json?limit=5&offset=5"
    },
    "size": 12,
    "entries": [
        {
            "url": "/people/george08/lists/OL13L",
            "full_url": "/people/george08/lists/OL13L/Various_Seeds_for_Testing",
            "name": "Various Seeds for Testing",
            "last_update": "2010-12-21T00:46:17.712513",
            "seed_count": 13,
            "edition_count": 13181
        },
        {
            "url": "/people/george08/lists/OL97L",
            "full_url": "/people/george08/lists/OL97L/Time_Travel",
            "name": "Time Travel",
            "last_update": "2010-12-17T18:27:14.781336",
            "seed_count": 5,
            "edition_count": 838
        },
        {
            ...
        },
        {
            ...
        },
        {
            ...
        }
    ]
}

Get lists of a seed

URL Format:

• http://openlibrary.org/books/OL1M/lists.json
  
• http://openlibrary.org/works/OL1W/lists.json
  
• http://openlibrary.org/authors/OL1A/lists.json
  
• http://openlibrary.org/subjects/place:san_francisco/lists.json

Sample Request:

GET http://openlibrary.org/works/OL8721462W/lists.json

Response:

{
    "size": 1,
    "links": {
        "self": "/works/OL8721462W/lists.json"
    },
    "entries": [
        {
            "url": "/people/george08/lists/OL43L",
            "full_url": "/people/george08/lists/OL43L/Top_100_Works_in_World_Literature_(in_progress)",
            "name": "Top 100 Works in World Literature (in progress)",
            "last_update": "2010-12-21T04:17:33.140325",
            "seed_count": 28,
            "edition_count": 2105
        }
    ]
}

List

Create a list:

Request:

POST /people/anand/lists HTTP/1.1
Content-Type: application/json
{
    "name": "18th Century Architecture",
    "description": "Studies of architectural practice, mainly English works",
    "tags": ["Architecture", "18th Century", "Drawings", "Buildings"],
    "seeds": [
        "/books/OL1M",
        "/subjects/gothic_architecture"
    ]
}

Response:

HTTP/1.1 201 Created
Location: http://openlibrary.org/user/anand/lists/OL1L

Read a list:

Request:

GET http://openlibrary.org/people/george08/lists/OL97L.json

Response:

{
    "links": {
        "editions": "/people/george08/lists/OL97L/editions",
        "self": "/people/george08/lists/OL97L",
        "seeds": "/people/george08/lists/OL97L/seeds",
        "subjects": "/people/george08/lists/OL97L/subjects"
    },
    "meta": {
        "last_modified": "2010-12-17T18:54:58.115370",
        "revision": 5,
        "created": "2010-12-17T18:50:35.064318"
    },
    "name": "Time Travel",
    "description": "Happy to lose myself in reading about that.",
    "seed_count": 5,
    "edition_count": 838
}

Update a list:

Request:

PUT /people/anand/list/OL1L HTTP/1.1
Content-Type: application/json
{
    "name": "18th Century Architecture",
    "description": "Studies of architectural practice, mainly English works",
    "tags": ["Architecture", "18th Century", "Drawings", "Buildings"],
    "seeds": [
        "subject:gothic_architecture"
    ]
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json
{"key": "/people/anand/list/OL1L", "revision": 3}

Get seeds of a list

Request:

GET http://openlibrary.org/people/george08/lists/OL97L/seeds.json

Response:

{
    "size": 5,
    "links": {
        "self": "/people/george08/lists/OL97L/seeds",
        "list": "/people/george08/lists/OL97L"
    },
    "entries": [
        {
            "url": "/books/OL24331810M",
            "full_url": "/books/OL24331810M/The_Time_Machine",
            "type": "edition",
            "title": "The Time Machine",
            "last_update": "2010-12-17T18:27:14.781336",
            "work_count": 1,
            "edition_count": 1,
            "ebook_count": 1,
            "picture": {
                "url": "http://covers.openlibrary.org/b/id/6570017-S.jpg"
            }
        },
        {
            "url": "/books/OL22864669M",
            "full_url": "/books/OL22864669M/A_Connecticut_Yankee_in_King_Arthur's_Court",
            "type": "edition",
            "title": "A Connecticut Yankee in King Arthur's Court",
            "last_update": "2010-09-06T02:05:15.820687",
            "work_count": 1,
            "edition_count": 1,
            "ebook_count": 7,
            "picture": {
                "url": "http://covers.openlibrary.org/b/id/6031475-S.jpg"
            }
        },
        {
            ...
        },
        {
            ...
        },
        {
            ...
        }
    ]
}

Add/delete a seed from a list:

Request:

POST /people/anand/lists/OL1L/seeds HTTP/1.1
Content-Type: application/json
{
    "add": [
        "/subjects/gothic_architecture"
    ],
    "remove": [
        "/works/OL1958650W"
    ]
}

Response:

200 OK HTTP/1.1
Content-Type: application/json
{"ok": "true"}

Get editions of a list:

Request:

GET http://openlibrary.org/people/george08/lists/OL97L/editions.json?limit=2

Response:

{
    "links": {
        "self": "/people/george08/lists/OL97L/editions.json?limit=2",
        "next": "/people/george08/lists/OL97L/editions.json?limit=2&offset=2",
        "list": "/people/george08/lists/OL97L"
    },
    "size": 838,
    "entries": [
        {
            "number_of_pages": 216,
            "table_of_contents": [...],
            "series": ["Buckram series"],
            "covers": [6570017],
            "lc_classifications": ["PZ3.W465 Ti"],
            "latest_revision": 6,
            "ocaid": "timemachineinven00well",
            "subtitle": "an invention",
            "source_records": ["ia:timemachineinven00well"],
            "title": "The Time Machine",
            "languages": [
                {
                    "key": "/languages/eng"
                }
            ],
            "publish_country": "nyu",
            "by_statement": "by H. G. Wells",
            "oclc_numbers": [
                "002345875"
            ],
            "type": {
                "key": "/type/edition"
            },
            "revision": 6,
            "publishers": [
                "H. Holt and Company"
            ],
            "last_modified": {
                "type": "/type/datetime",
                "value": "2010-12-17T18:27:14.781336"
            },
            "key": "/books/OL24331810M",
            "authors": [
                {
                    "key": "/authors/OL13066A"
                }
            ],
            "publish_places": [
                "New York"
            ],
            "pagination": "vii, 216 p.",
            "classifications": {},
            "created": {
                "type": "/type/datetime",
                "value": "2010-08-12T15:25:20.784688"
            },
            "lccn": [
                "08036642"
            ],
            "identifiers": {},
            "publish_date": "1895",
            "works": [
                {
                    "key": "/works/OL52267W"
                }
            ]
        },
        {
            ...
        }
    ]
}

Get subjects of a list:

Request:

GET http://openlibrary.org/people/george08/lists/OL97L/subjects.json?limit=5

Response:

{
    "links": {
        "self": "/people/george08/lists/OL97L/subjects",
        "list": "/people/george08/lists/OL97L"
    },
    "subjects": [
        {
            "count": 256,
            "url": "/subjects/general_relativity_(physics)",
            "name": "General relativity (Physics)"
        },
        ...
    ],
    "places": [
        {
            "count": 1,
            "url": "/subjects/place:great_britain",
            "name": "Great Britain"
        },
        ...
    ],
    "people": [
        {
            "count": 1,
            "url": "/subjects/person:mark_twain_(1835-1910)",
            "name": "Mark Twain (1835-1910)"
        },
        ...
    ],
    "times": [
        {
            "count": 1,
            "url": "/subjects/time:19th_century",
            "name": "19th century"
        }
    ]
}