Skip to content

Readings

Jump to bottom Edit New page
Christof Dorner edited this page Aug 19, 2012 · 34 revisions

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"}}'

Add a custom footer
Add a custom sidebar
Clone this wiki locally