Readings - 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.

Readings

This part of the API has to do with requesting information about readings, or updating their content. If you want to create a reading, see Books for more information.

Available endpoints

/readings, GET
/readings/#{id}, GET, PUT, DELETE
/readings/#{id}/pings, POST
/readings/#{id}/periods, GET
/readings/#{id}/locations, GET
/readings/#{id}/highlights, GET, POST
/readings/#{id}/comments, GET, POST

Representation

An example of the JSON representation of a reading

{
  "id": 21,
  "state": 3,
  "private": false,
  "recommended": false,
  "closing_remark": "The stories about the early days of Thefacebook was really great, hearing about how they were hacking like crazy from that house in Palo Alto. Although, like all tech-books it slowed down towards the end. The last 100 pages was a fight.",
  "touched_at": "2010-12-14T10:36:21Z",
  "started_at": "2010-11-29T20:25:56Z",
  "finished_at": "2010-12-14T10:36:31Z",
  "abandoned_at": null,
  "created_at": "2010-11-29T20:25:56Z",
  "duration": 25500,
  "progress": 1.0,
  "estimated_time_left": 0,
  "average_period_time": "5100.0",
  "book": {
    "id": 12,
    "title": "The Facebook Effect",
    "author": "David Kirkpatrick",
    "permalink": "the-facebook-effect",
    "permalink_url": "http://readmill.com/books/the-facebook-effect",
    "cover_url": "http://static.readmill.com/covers/cd515b733e3963d467bd15128a666724-medium.png?1291062356"
  },
  "user": {
    "id": 2,
    "username": "henrik",
    "firstname": "Henrik",
    "fullname": "Henrik Berggren",
    "avatar_url": "http://static.readmill.com/avatars/c4f503989a8115d83d198c8dd2635ef4-medium.png?1304016207",
    "followers": 20,
    "followings": 120,
    "uri": "http://api.readmill.com/users/2",
    "permalink_url": "http://readmill.com/henrik"
  },
  "permalink_url": "http://readmill.com/henrik/reads/the-facebook-effect",
  "uri": "http://api.readmill.com/readings/21",
  "periods": "http://api.readmill.com/readings/21/periods",
  "locations": "http://api.readmill.com/readings/21/locations",
  "highlights":"http://api.readmill.com/readings/21/highlights",
  "comments":"http://api.readmill.com/readings/21/comments",
  "comments_count": 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,

state is a description of the state the reading is in, there are four states, 1 => Interesting, 2 => Reading, 3 => Finished, 4 => Abandoned.

API Calls

GET /readings

Retrieves the representation of either the 20 newest readings, or the result of a range query.

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

Response

200 and a list of readings.

Examples

curl http://api.readmill.com/readings?client_id=CLIENTID&from=1&to=25&count=5

GET /readings/#{id}

Retrieves the representation of a single reading by ID.

Parameters

id: The id of the reading you want to get information about.

Authentication

client_id
access_token (For private readings)

Response

Success: 200 and a single reading.
Failure: 404

Examples

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

PUT /readings/#{id}

Update a reading for the current user.

Parameters

id (integer): The id of the reading you want to update
reading[state] '(integer): The state of the current reading. (1 => Interesting, 2 => Open, 3 => Finished, 4 => Abandoned)
reading[private] '(boolean): Is the reading private? (true/false)
reading[recommended] '(boolean): Is this book recommended? (Optional)
reading[closing_remark] '(string): The closing remark for the book. (Optional)

Authentication

access_token

Response

Success: 200
Failure: 422

Examples

curl -X PUT http://api.readmill.com/readings/1?access_token=TOKEN -H 'Content-Type: application/json' -d '{"reading": {"state": 3, "is_private": false, "closing_remark": "Great book!" }}'

DELETE /readings/#{id}

Remove a reading from the current user.

Parameters

id: The id of the reading you want to delete

Authentication

access_token

Response

Success: 200
Failure: 401

Examples

curl -X DELETE http://api.readmill.com/readings/1

POST /readings/#{id}/pings

Send a ping to indicate a reading session for this reading.

Parameters

id (integer): The id of the reading you want to send a ping to.
ping[identifier] '(string): A unique identifier that groups pings together for a reading session, select something that makes sense for your application.
ping[progress] '(float): Progress given as a float between 0.0 and 1.0.
ping[duration] '(integer): Time since last ping, in seconds. (Optional)
ping[occurred_at] '(string): The time the ping was made, as an RFC3339 formatted string. (Optional)
ping[lat] '(float): The latitude of the location at the time of the ping as a float. (Optional)
ping[lng] '(float): The longitude of the location at the time of the ping as a float. (Optional)

Authentication

access_token

Response

Success: 201
Failure: 422, 401

Examples

curl -X POST http://api.readmill.com/readings/1/pings?access_token=TOKEN -H 'Content-Type: application/json' -d '{"ping": {"identifier": "0.5361565119655187", "progress": 0.5}}'

GET /readings/#{id}/periods

Retrieves all the reading periods for a specific reading.

Parameters

id: The id of the reading you want to retrieve periods for.

The default sort order is descending on started_at.

Authentication

client_id
access_token (For private readings)

Response

Success: 200 and an array of periods.
Failure: 404

Examples

curl http://api.readmill.com/readings/21/periods?client_id=CLIENTID

GET /readings/#{id}/locations

Retrieves all the locations for a specific reading.

Parameters

id: The id of the reading you want to retrieve locations for.

Authentication

client_id
access_token (For private readings)

Response

Success: 200 and an array of locations.
Failure: 404

Examples

curl http://api.readmill.com/readings/644/locations?client_id=CLIENTID

GET /readings/#{id}/comments

Get all the comments for a specific reading

Parameters

id: The id for the reading
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)

The default sort order is ascending on posted_at.

Authentication

client_id
access_token (For private readings)

Response

200 and an array of comments.

Examples

curl http://api.readmill.com/readings/644/comments?client_id=CLIENTID

POST /readings/#{id}/comments

Add a comment to a reading

Parameters

comment[content] '(string): The content of the comment.

Authentication

access_token

Response

Success: 201 and a location
Failure: 422

Examples

curl -X POST http://api.readmill.com/readings/501/comments?access_token=TOKEN -H 'Content-Type: application/json' -d '{"comment": {"content": "A comment"}}'

GET /readings/#{id}/highlights

Get all the highlights for a specific reading

Parameters

id: The id for the reading
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)

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

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

The default sort order is descending on highlighted_at.

Authentication

client_id
access_token (For private readings)

Response

200 and an array of highlights.

Examples

curl http://api.readmill.com/readings/644/highlights?client_id=CLIENTID

POST /readings/#{id}/highlights

Add a highlight to a reading. You also have the option to include a comment in the same request.

Parameters

highlight[content] '(string): The content of the highlight.
highlight[position] '(float): The position of the highlight inside of the book. This is a represented as float percentage, ex. 0.2
highlight[locators] '(hash): Flexible hash for locating the highlight (detailed information can be found at Highlight-locators) (optional)
highlight[highlighted_at] '(string): When the highlight was created, for offline purposes. (optional)
comment[content] '(string): A comment that is added to the highlight upon creation. (optional)

Authentication

access_token

Response

Success: 201 and a location
Failure: 422

Examples

curl -X POST http://api.readmill.com/readings/501/highlights?access_token=TOKEN -H 'Content-Type: application/json' -d '{"highlight": {"content": "A highlight", "position":0.2, "pre":"Hello my dear friend ", "post":" and there she goes"}}'