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

Highlights

This part of the API has to do with interacting with highlights.

Available endpoints

  • /highlights, GET
  • /highlights/#{id}, GET, PUT, DELETE
  • /highlights/#{id}/comments, GET, POST

Representation

An example of the JSON representation of a highlight below,

{
    "id":1,
    "reading_id":49,
    "position":0.0238095,
    "content":"One morning,
     when Gregor Samsa woke from troubled dreams,
     he found himself transformed in his bed into a horrible vermin.",
    "highlighted_at":"2011-07-06T12:00:04Z",
    "uri":"http://api.readmill.com/highlights/1",
    "permalink":"8cfe",
    "permalink_url":"http://readmill.com/david/reads/metamorphosis/highlights/8cfe",
    "locators":
    {
        "pre":"",
        "mid":"One morning,
         when Gregor Samsa woke from troubled dreams,
         he found himself transformed in his bed into a horrible vermin.",
        "post":"He lay on his armour-like back,
         and if he lifted his head a little he could see his brown belly,
         slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment. His many legs,
         pit"
    },
    "user":
    {
        "id":5,
        "username":"david",
        "firstname":"David",
        "fullname":"David Kjelkerud",
        "avatar_url":"http://static.readmill.com/avatars/cc793a951d9b276afcc7d1bee98ca99a-medium.png?1321020637",
        "followers":174,
        "followings":180,
        "uri":"http://api.readmill.com/users/5",
        "permalink_url":"http://readmill.com/david"
    },
    "comments":"http://api.readmill.com/highlights/1/comments",
    "comments_count":3
}

Detailed info on the locators key can be found at Highlight-locators.

API Calls

GET /highlights

Get all the public highlights

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)
  • order: A timestamp key eg "highlighted_at". (required when making a range query)
  • count: The number of results to return, defaults to 20, limited to 100. (optional)

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

The default sort order is descending on highlighted_at.

Authentication

  • client_id

Response

  • 200 and an array of highlights.

Examples

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

Making a range query:

curl http://api.readmill.com/readings/644/highlights?client_id=CLIENTID&order=highlighted_at&from=2012-01-21T22:00:00Z&to=2012-01-21T23:00:00Z

GET /highlights/#{id}

Retrieves the representation of a single highlight.

Parameters

  • id: The id of the highlight.

Authentication

  • client_id

Response

  • Success: 200 and a highlight.
  • Failure: 404

Examples

curl http://api.readmill.com/highlights/1?client_id=CLIENT_ID

PUT /highlights/#{id}

Update a highlight

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 (optional)
  • 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)

Authentication

  • access_token

Response

  • Success: 200
  • Failure: 422

Examples

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

DELETE /highlights/#{id}

Deletes a highlight

Parameters

  • id: The id of the highlight to delete.

Authentication

  • access_token

Response

  • Success: 200
  • Failure: 404

Examples

curl -X DELETE http://api.readmill.com/highlights/370?access_token=TOKEN

GET /highlights/#{id}/comments

Get all the comments for a specific highlight

Parameters

  • id: The id for the highlight

The default sort order is ascending on posted_at.

Authentication

  • client_id
  • access_token (For private highlights, part of a private reading)

Response

  • 200 and an array of comments.

Examples

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

POST /highlights/#{id}/comments

Add a comment to a highlight

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/highlights/501/comments?access_token=TOKEN -H 'Content-Type: application/json' -d '{"comment": {"content": "A comment"}}'