Books - readmill/API GitHub Wiki

This is the documentation for v1 of the Readmill API which is deprecated and will be discontinued on 2012-12-16. Please upgrade to v2, the new developer documentations are at developers.readmill.com.

Books

This part of the API has to do with requesting information on specific books, but also to add books to Readmill, and add readings to books.

Available endpoints

  • /books, GET, POST
  • /books/match, GET
  • /books/#{id}, GET
  • /books/#{id}/readings, GET, POST

Representation

An example of the JSON representation of 'Ulysses' by James Joyce:

{
  "id": 9,
  "title": "Ulysses",
  "author": "James Joyce",
  "isbn": "9780554354088",
  "story": "Stately- plump Buck Mulligan...",
  "published_at": "2008-08-18",
  "language": "en",
  "permalink": "ulysses",
  "permalink_url": "http://readmill.com/books/ulysses",
  "uri": "http://api.readmill.com/books/9",
  "cover_url": "http://static.readmill.com/covers/800-medium.png",
  "assets": [
    {
      "vendor": "feedbooks",
      "uri": "http://www.feedbooks.com/book/1232.epub",
      "acquisition_type": 0
    }
  ]
}

Most fields are hopefully pretty self-explanatory from only the name and value, but some might not be either due to surprising names or values,

  • story includes a short summary of the book and is intended for presentation in a user interface, it contains only plain text.
  • published_at is when the edition with this ISBN is published, not when the book was originally released.
  • assets contains information about where you could buy or download this book. In this case it is available for free from feedbooks.com at the given URI.

API Calls

GET /books

Retrieves the representation of either the 20 newest books or the result of a search.

Parameters

  • q: A string to search for. (optional, search)
  • count: The number of results to return, defaults to 20, limited to 100. (optional)

If q is included, the query is always a search and ignores the other parameters, otherwise it returns the newest books based on the count parameter.

If neither are included in the query, the count newest books are returned.

Authentication

  • client_id

Response

  • 200 and an array of books.

Examples

curl http://api.readmill.com/books?client_id=CLIENTID&q=Moby

GET /books/match

Retrieves the representation of the best matching book. This is meant to be used when suggesting which book to connect for the user. See the provided UI docs for details.

Parameters

  • q[title]: The title of the book. (optional)
  • q[author]: The name of the author. (optional)
  • q[isbn]: The ISBN number of the book. (optional)

If q[isbn] is included, a match against ISBN is tried first. If that fails, a match against q[title] and q[author] is attempted.

Authentication

  • client_id

Response

  • Success: 200 and a book.
  • Failure: 404

Examples

curl http://api.readmill.com/books/match?client_id=CLIENTID&q[title]=Anthem&q[author]=ayn%20rand

POST /books

Add a book to Readmill

Parameters

  • book[author] '(string): The author of the book, multiple authors should be separated with a comma.
  • book[title] '(string): The title of the book.
  • book[isbn] '(string): The ISBN number of the book, without any hyphens. (optional)

Authentication

  • access_token

Response

  • Success: 201 and a permalink to the new book in the Location header.
  • Failure: 422

Examples

Example - curl -X POST http://api.readmill.com/books?access_token=TOKEN -H 'Content-Type: application/json' -d '{"book": {"author": "Ingemar Ottosson, Thomas Ekholm", "title": "Japans Historia", "isbn": "9789186297657" }}'

GET /books/#{id}

Retrieves information about a book by identifier

Parameters

  • id: The id of the book we want to retrieve information about.

Authentication

  • client_id

Response

  • Success: 200 and a book.
  • Failure: 404

Examples

curl http://api.readmill.com/books/1?client_id=CLIENT_ID

POST /books/#{id}/readings

Add a reading for the current user

Parameters

  • reading[state] '(integer): The state of the current reading. (1 => Interesting, 2 => Reading, 3 => Finished, 4 => Abandoned)
  • reading[private] '(boolean): Is the reading private? (true/false)
  • reading[closing_remark] '(string): The closing remark for the book. (Optional)

Authentication

  • access_token

Response

  • Success: 201 and a permalink to the book in the Location header.
  • Failure: 422 (insufficient parameters) or 409 (user already has a reading of this book, uri to that reading is in the 'Location' header)

Examples

curl -X POST http://api.readmill.com/books/676/readings -H 'Content-Type: application/json -d '{"access_token": TOKEN, "reading": {"state": 2, "private": false }}'

GET /books/#{id}/readings

Lists all reading for a book

Parameters

  • from: The first date to be included. (optional, range query)
  • to: The last date, not inclusive. (optional, range query)
  • count: The number of results to return, defaults to 20, limited to 100. (optional)
  • order: The sort order of the collection. Valid options are touched_at (descending), created_at (descending), popular (optional, only touched_at and created_at allowed when using range queries)
  • filter: Ways to filter the set. Valid options are followings (optional but requires access_token when used)
  • highlights_count[from]: The first count of highlights to be included. (optional)
  • highlights_count[to]: The last count of highlights to be included. (optional)
  • states: Comma-separated list of interesting, reading, finished, abandoned. (optional)

If only from is included with a range query, to is assumed to be higher than the highest id available.

If only highlights_count[from] is included when filtering on highlights_count, highlights_count[to] is assumed to be higher than the highest highlights_count available.

If neither are included in the query, the count newest readings are returned.

The default sort order is descending on created_at.

Authentication

  • client_id
  • access_token (optional)

Response

  • 200 and a array of readings

Examples

curl http://api.readmill.com/books/676/readings?client_id=CLIENTID