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:

• 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

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?