Skip to content

Readings

Jump to bottom Edit New page
hinke edited this page Sep 30, 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.

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 Henrik's user 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",
  "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 => 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?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

  • Success: 200 and a single reading.
  • Failure: 404

Examples

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

{
  "id": 21,
  "state": 3,
  "private": false,
  "recommended": false,
...
}

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

  • 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 identifier of the reading you want to update

Authentication

  • OAuth 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 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

  • 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 identifier of the reading you want to retrieve periods for.

Authentication

  • Client ID
  • OAuth 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

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

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

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

Examples

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

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

GET /readings/#{id}/comments

Get all the comments for a specific reading

Parameters

  • id: The identifier for the reading

Authentication

  • Client ID
  • OAuth Token (For private readings)

Response

  • 200 and an array of comments.

Examples

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

[
  {
    "id": 127,
    "reading_id": 644,
    "highlight_id": null,
    "content": "\"autoload allows us to lazily load a class when it is first referenced. So when we want to load MailForm we annotate it has a constant called Base defined in mail_form/base.rb. When MailForm::Base is referenced for the first time, Ruby loads the mail_form/base.rb file.\"",
    "posted_at": "2011-04-20T19:06:41Z",
    "uri": "http://api.readmill.com/comments/127"
  } ... 
]

POST /readings/#{id}/comments

Add a comment to a reading

Parameters

  • comment[content]: The content of the comment.

Authentication

  • OAuth 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 identifier for the reading

Authentication

  • Client ID
  • OAuth Token (For private readings)

Response

  • 200 and an array of highlights.

Examples

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

[
    {
        "highlighted_at":"2011-08-08T14:18:52Z",
        "position":0.2,
        "permalink":"5f8a",
        "uri":"http://api.readmill.local/highlights/9",
        "post":null,
        "comments":"http://api.readmill.local/highlights/9/comments",
        "pre":null,
        "id":9,
        "content":"Open iTunes on your computer. Select your iPad in the sidebar,
         go to Apps,
         scroll down and select Readmill under File Sharing. Drag\u2019n\u2019drop your books to transfer.",
        "reading_id":644,
        "comments_count":0,
        "user":
        {
            "avatar_url":"http://static.readmill.local/avatars/cd958d19cadce04ca2a7b154b3778aa1-medium.png?1311690158",
            "username":"david",
            "fullname":"david",
            "id":1,
            "permalink_url":"http://api.readmill.local/users/1"
        },
        "permalink_url":"http://readmill.local/david/reads/communication-power/highlights/5f8a"
    } ...
]

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

  • OAuth 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