Skip to content

Readings

Jump to bottom Edit New page
hinke edited this page Sep 7, 2011 · 34 revisions

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.

Representation

An example of the JSON representation of Henrik Berggren's user could be like below,

{
  "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",
    "fullname": "Henrik Berggren",
    "avatar_url": "http://static.readmill.com/avatars/c4f503989a8115d83d198c8dd2635ef4-medium.png?1304016207",
    "permalink_url": "http://api.readmill.com/users/2"
  },
  "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"
}

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 => Open, 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 identifier to be included (optional)
  • to: The last identifier, not inclusive (optional)
  • 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 identifier available.

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

Authentication

  • Client ID

Response

  • 200 and a list of readings.

Examples

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

[
  {
    "id": 21,
    "state": 3,
    "private": false,
    "recommended": false,
    "closing_remark": ...,
    "author": "David Kirkpatrick",
    "permalink": "the-facebook-effect",
    "permalink_url": "http://readmill.com/books/the-facebook-effect",
    "cover_url": "http://readmill.com/covers/cd515b733e3963d467bd15128a666724-medium.png?1291062356"
  } ...
]

GET /readings/#{id}

Retrieves the representation of a single reading by ID.

Parameters

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

Authentication

  • Client ID
  • OAuth Token (For private readings)

Response

  • Positive: 200 and a single reading.
  • Negative: 404

Examples

Positive example - curl http://api.readmill.com/readings/21.json?client_id=CLIENTID

{
  "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",
    "fullname": "Henrik Berggren",
    "avatar_url": "http://static.readmill.com/avatars/c4f503989a8115d83d198c8dd2635ef4-medium.png?1304016207",
    "permalink_url": "http://api.readmill.com/users/2"
  },
  "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"
}

Negative example - curl http://api.readmill.com/readings/9001.json?client_id=CLIENTID

{
  "error": "404 - Not Found"
}

PUT /readings/#{id}

Update a reading for the current user.

Parameters

  • id: The identifier 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

  • OAuth Token

Response

  • 200

Examples

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

DELETE /readings/#{id}

Remove a reading from the current user.

Parameters

  • id: The identifier of the reading you want to update

Authentication

  • OAuth Token

Response

  • 200

Examples

Example - 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 identifier of the reading you want to send a ping for.
  • 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, used for when you are offline and cannot send pings when they are made as an ISO 8601 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

  • OAuth Token

Response

  • 200

Examples

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

GET /readings/#{id}/periods

Retrieves all the reading periods for a specific reading.

Parameters

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

Authentication

  • Client ID
  • OAuth Token (For private readings)

Response

  • Positive: 200 and an array of periods.
  • Negative: 404

Examples

Positive example - curl http://api.readmill.com/readings/21/periods.json?client_id=CLIENTID

[
  {
    "id": 13,
    "reading_id": 21,
    "user_id": 2,
    "started_at": "2010-12-14T10:36:21Z",
    "duration": 300,
    "progress": 0.87,
    "locations": []
  } ...
]

Negative example - curl http://api.readmill.com/readings/9001/periods.json?client_id=CLIENTID

{
  "error": "404 - Not Found"
}

GET /readings/#{id}/locations

Retrieves all the locations for a specific reading.

Parameters

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

Authentication

  • Client ID
  • OAuth Token (For private readings)

Response

  • Positive: 200 and an array of locations.
  • Negative: 404

Examples

Positive example - curl http://api.readmill.com/readings/644/locations.json?client_id=CLIENTID

[
  {
    "id": 12,
    "period_id": 176,
    "reading_id": 644,
    "lat": 59.3177,
    "lng": 18.031
  } ...
]

Negative example - curl http://api.readmill.com/readings/9001/periods.json?client_id=CLIENTID

{
  "error": "404 - Not Found"
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally