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: The id of the reading you want to update
reading[state]: The state of the current reading. (1 => Interesting, 2 => Open, 3 => Finished, 4 => Abandoned)
reading[private]: Is the reading private? (true/false)
reading[recommended]: Is this book recommended? (Optional)
reading[closing_remark]: 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: The id of the reading you want to send a ping to.
ping[identifier]: A unique identifier that groups pings together for a reading session, select something that makes sense for your application.
ping[progress]: Progress given as a float between 0.0 and 1.0.
ping[duration]: Time since last ping, in seconds. (Optional)
ping[occured_at]: The time the ping was made, as an RFC3339 formatted string. (Optional)
ping[lat]: The latitude of the location at the time of the ping as a float. (Optional)
ping[lng]: 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.

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

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]: 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

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]: The content of the highlight.
highlight[position]: The position of the highlight inside of the book. This is a represented as float percentage, ex. 0.2
highlight[pre]: A few words before the highlight. (optional)
highlight[post]: A few words after the highlight. (optional)
highlight[highlighted_at]: When the highlight was created, for offline purposes. (optional)
comment: 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"}}'

Readings

Readings

Available endpoints

Representation

API Calls

GET /readings

Parameters

Authentication

Response

Examples

GET /readings/#{id}

Parameters

Authentication

Response

Examples

PUT /readings/#{id}

Parameters

Authentication

Response

Examples

DELETE /readings/#{id}

Parameters

Authentication

Response

Examples

POST /readings/#{id}/pings

Parameters

Authentication

Response

Examples

GET /readings/#{id}/periods

Parameters

Authentication

Response

Examples

GET /readings/#{id}/locations

Parameters

Authentication

Response

Examples

GET /readings/#{id}/comments

Parameters

Authentication

Response

Examples

POST /readings/#{id}/comments

Parameters

Authentication

Response

Examples

GET /readings/#{id}/highlights

Parameters

Authentication

Response

Examples

POST /readings/#{id}/highlights

Parameters

Authentication

Response

Examples

Clone this wiki locally