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

Users

This part of the API has to do with requesting information on specific users, either via an id, or by requesting information about the user the user which is authenticated via OAuth.

Available endpoints

  • /me, GET (See also me/connections here: Connections)
  • /users/#{id}, GET
  • /users/#{user_id}/readings, GET
  • /users/#{user_id}/readings/exists, GET
  • /users/#{user_id}/readings/#{reading_id}, GET

Representation

An example of the JSON representation of a user:

{
    "id":1,
    "username":"christoffer",
    "firstname":"Christoffer",
    "lastname":"Klang",
    "fullname":"Christoffer Klang",
    "country":"Sweden",
    "city":"Stockholm",
    "created_at":"2010-11-21T19:44:34Z",
    "website":"http://readmill.com/christoffer",
    "description":"Mostly reading tech stuff. And cheesy thrillers on vacations.",
    "uri":"http://api.readmill.com/users/1",
    "permalink_url":"http://readmill.com/christoffer",
    "books_interesting":14,
    "books_open":3,
    "books_finished":9,
    "books_abandoned":3,
    "readings":"http://api.readmill.com/users/1/readings",
    "avatar_url":"http://static.readmill.com/avatars/d2e1cecb6f537bdb789ec0fce16903e1-medium.png?1303978657",
    "followers":67,
    "followings":126
}

API Calls

GET /me

Retrieves the representation of the user corresponding to the authentication token.

Authentication

  • access_token

Response

  • 200 and a single user.

Examples

curl http://api.readmill.com/me?access_token=TOKEN

Notice that you receive the user's email address when requesting /me. This is not the case when requesting users with an id (see below).

GET /users/#{id}

Retrieves the representation of a single user by id.

Parameters

  • id: The id of the user you want to retrieve.

Authentication

  • client_id

Response

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

Examples

curl http://api.readmill.com/users/2?client_id=CLIENTID

GET /users/#{id}/readings

Retrieves an array of readings corresponding to the user with the specified ID.

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) (optional)
  • 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
  • access_token (if you want to include a users private readings)

Response

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

curl http://api.readmill.com/users/101/readings?client_id=CLIENT_ID

GET /users/#{user_id}/readings/exists

Checks if a user has a specific reading.

Parameters

  • q[title]: The title of the book. (optional)
  • q[author]: The name of the author. (optional)
  • q[isbn]: The ISBN number of the book. (optional)

If q[isbn] is included, a match against ISBN is tried first. If that fails, a match against q[title] and q[author] is attempted.

Authentication

  • access_token

Response

  • Success: 200 and a permalink to the new book in the Location header.
  • Failure: 404

curl http://api.readmill.com/users/101/readings?client_id=CLIENT_ID&q[title]=Ulysses

GET /users/#{user_id}/readings/#{reading_id}

Retrieves a reading corresponding to the reading id and the specified user.

Parameters

  • user_id: The id of the user you want to get a reading for.
  • reading_id: The id of the reading you want to get.

Authentication

  • client_id
  • access_token (if you are requesting a private reading)

Response

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

curl http://api.readmill.com/users/101/readings/1370?client_id=CLIENT_ID