Open Library logo
Last edited by Anand Chitipothu
September 24, 2010 | History

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/anand/lists.json

Response:

{
    "key": "/books/OL1M",
    "list_count": 100,
    "links": {
        "self": "http://openlibrary.org/people/anand/lists.json",
        "next": "http://openlibrary.org/people/anand/lists.json?offset=20",
    }
    "lists": [
        {"key": "/user/anand/lists/OL1L"},
        {"key": "/user/anand/lists/OL8L"},
    ]
}

Get lists of a seed

URL Format:

Response:

{
    "list_count": 100,
    "links": {
        "self": "http://openlibrary.org/books/OL1M/lists.json",
        "next": "http://openlibrary.org/books/OL1M/lists.json?offset=20",
    }
    "lists": [
        {"key": "/user/anand/lists/OL1L"},
        {"key": "/user/george08/lists/OL12L"},
    ]
}

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": [
        "subject: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/anand/lists/OL1L.json

Response:

{
    "key": "/people/anand/lists/OL1L",
    "name": "18th Century Architecture",
    "description": "Studies of architectural practice, mainly English works",
    "tags": ["Architecture", "18th Century", "Drawings", "Buildings"],
    "seeds": [
        "subject:gothic_architecture"
    ],
    "created": {
        "type": "/type/datetime",
        "value": "2010-09-01T00:00:00"
    }
}

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}

Add/delete a seed from a list:

Request:

POST /people/anand/lists/OL1L/seeds HTTP/1.1
Content-Type: application/json
{
    "add": [
        "subject:gothic_architecture"
    ],
    "delete": [
        {"key": "/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/anand/lists/OL1L/editions.json?offset=40

Response:

{
    "key": "/people/anand/lists/OL1M",
    "links": {
        "self": "http://openlibrary/people/anand/links/OL1L/editions.json?offset=40",
        "next": "http://openlibrary/people/anand/links/OL1L/editions.json?offset=60&limit=20",
        "prev": "http://openlibrary/people/anand/links/OL1L/editions.json?offset=20&limit=20"
    }
    "edition_count": "2345",
    "editions": [
        {"key": "/books/OL124M"},
        {"key": "..."},
        ...
    ]
}

Get subjects of a list:

Request:

GET http://openlibrary.org/people/anand/lists/OL1L/subjects.json

Response:

{
    "key": "/people/anand/lists/OL1M",
    "links": {
        "self": "http://openlibrary.org/people/anand/lists/OL1L/subjects.json"
    }
    "subjects": [{
            "name": "Architecture",
            "key": "/subjects/architecture"
    }],
    "places": [{
        "name": "Rome",
        "key": "/subjects/place:rome"
    }],
    "people": [],
    "times": [{
        "name": "18th Century",
        "key": "/subjects/time:18th_century"
    }]
}

Is it better to provide subjects, places, people and times separately? or should all they be combined into subjects and support pagination?

History

December 21, 2010 Edited by Anand Chitipothu Edited without comment.
December 21, 2010 Edited by Anand Chitipothu Provides uniform interface accessing and updating for seeds.
December 21, 2010 Edited by Anand Chitipothu Updated Lists API.
September 27, 2010 Edited by Anand Chitipothu API changes
September 24, 2010 Created by Anand Chitipothu Upcoming Lists API