Skip to content

Users

Jump to bottom Edit New page
christoffer edited this page Sep 20, 2011 · 21 revisions

Users

This part of the API has to do with requesting information on specific users, either via an identifier, or by requesting information about the user that provided the current authorization token.

Available endpoints

  • /me, GET
  • /users/#{id}, GET
  • /users/#{user_id}/readings, GET
  • /users/#{user_id}/readings/#{reading_id}, GET

Representation

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

{
  "id": 2,
  "username": "henrik",
  "firstname": "Henrik",
  "lastname": "Berggren",
  "fullname": "Henrik Berggren",
  "country": "Sweden",
  "city": "Stockholm",
  "website": "http://henrikberggren.com",
  "description": "Passionate reader of internet lit and crime novels",
  "uri": "http://api.readmill.com/users/2",
  "permalink_url":"http://readmill.com/henrik",
  "books_interesting":23,
  "books_open":2,
  "books_finished":3,
  "books_abandoned":0,
  "readings":"http://api.readmill.com/users/2/readings",
  "avatar_url":"http://static.readmill.com/avatars/c4f5.png",
  "followers":125,
  "followings":115
}

All of the fields should be self-explanatory from the name and value.

API Calls

GET /me

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

Authentication

  • OAuth Token

Response

  • 200 and a single user.

Examples

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

{
  "id": 101,
  "username": "jensnockert",
  "firstname": "Jens",
  "lastname": "Nockert",
  "fullname": "Jens Nockert",
  "country": "Sweden",
  "city": "Lund",
  "website": "",
  "description": "",
  "uri": "http://api.readmill.com/users/101",
  "permalink_url": "http://readmill.com/jensnockert",
  "books_interesting": 1,
  "books_open": 1,
  "books_finished": 0,
  "books_abandoned": 0,
  "readings": "http://api.readmill.com/users/101/readings",
  "avatar_url": "http://static.readmill.com/avatars/d281aa934d75016e9f60c2db7e4a55e4-medium.png?1308255920",
  "followers": 2,
  "followings": 2,
  "email": "no@spam.plz"
}

Notice that you also receive the user's email address when requesting /me. This is not the case when requesting users by identifier (se below).

GET /users/#{id}

Retrieves the representation of a single user by ID.

Parameters

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

Authentication

  • Client ID

Response

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

Examples

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

{
  "id": 2,
  "username": "henrik",
  "firstname": "Henrik",
  "lastname": "Berggren",
  "fullname": "Henrik Berggren",
  "country": "Sweden",
  "city": "Stockholm",
  "website": "http://henrikberggren.com",
  "description": "Passionate reader of internet lit and crime novels",
  "uri": "http://api.readmill.com/users/2",
  "permalink_url": "http://readmill.com/henrik",
  "books_interesting": 24,
  "books_open": 2,
  "books_finished": 3,
  "books_abandoned": 0,
  "readings": "http://api.readmill.com/users/2/readings",
  "avatar_url": "http://static.readmill.com/avatars/c4f503989a8115d83d198c8dd2635ef4-medium.png?1304016207",
  "followers": 125,
  "followings": 117
}

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

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

GET /users/#{id}/readings

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

Parameters

  • id: The ID of the user you want to get information about.

Authentication

  • Client ID
  • OAuth Token (if you want to include a users private readings)

Response

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

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

[
  {
    "id": 1370,
    "state": 2,
    "private": false,
    "closing_remark": null,
    "touched_at": "2011-06-28T11:13:10Z",
    "started_at": "2011-06-28T10:39:43Z",
    "finished_at": null,
    "abandoned_at": null,
    "created_at": "2011-06-28T10:39:43Z",
    "duration": 1200,
    "progress": 0.7,
    "estimated_time_left": 500,
    "average_period_time": "600.0",
    "book": {
      "id": 667,
      "title": "Around the World in Eighty Days",
      "author": "Jules Verne",
      "permalink": "around-the-world-in-eighty-days",
      "permalink_url": "http://readmill.com/books/around-the-world-in-eighty-days",
      "cover_url": "http://static.readmill.com/images/default-cover-medium.png"
    },
    "user": {
      "id":101,
      "username": "jensnockert",
      "fullname": "Jens Nockert",
      "avatar_url": "http://static.readmill.com/avatars/d281aa934d75016e9f60c2db7e4a55e4-medium.png?1308255920",
      "permalink_url": "http://api.readmill.com/users/101"
    },
    "permalink_url": "http://readmill.com/jensnockert/reads/around-the-world-in-eighty-days",
    "uri": "http://api.readmill.com/readings/1370",
    "periods": "http://api.readmill.com/readings/1370/periods",
    "locations": "http://api.readmill.com/readings/1370/locations",
    "highlights": "http://api.readmill.com/readings/1370/highlights"
  } ...
]

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

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

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

Retrieves a reading representation corresponding to the reading identifer 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
  • OAuth Token (if you are requesting a private reading)

Response

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

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

{
  "id": 1370,
  "state": 2,
  "private": false,
  "closing_remark": null,
  "touched_at": "2011-06-28T11:13:10Z",
  "started_at": "2011-06-28T10:39:43Z",
  "finished_at": null,
  "abandoned_at": null,
  "created_at": "2011-06-28T10:39:43Z",
  "duration": 1200,
  "progress": 0.7,
  "estimated_time_left": 500,
  "average_period_time": "600.0",
  "book": {
    "id": 667,
    "title": "Around the World in Eighty Days",
    "author": "Jules Verne",
    "permalink": "around-the-world-in-eighty-days",
    "permalink_url": "http://readmill.com/books/around-the-world-in-eighty-days",
    "cover_url": "http://static.readmill.com/images/default-cover-medium.png"
  },
  "user": {
    "id": 101,
    "username": "jensnockert",
    "fullname": "Jens Nockert",
    "avatar_url": "http://static.readmill.com/avatars/d281aa934d75016e9f60c2db7e4a55e4-medium.png?1308255920",
    "permalink_url": "http://api.readmill.com/users/101"
    },
  "permalink_url": "http://readmill.com/jensnockert/reads/around-the-world-in-eighty-days",
  "uri": "http://api.readmill.com/readings/1370",
  "periods": "http://api.readmill.com/readings/1370/periods",
  "locations": "http://api.readmill.com/readings/1370/locations",
  "highlights":"http://api.readmill.com/readings/1370/highlights"
}

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

{
  "error": "404 - Not Found"
}
Add a custom footer
Add a custom sidebar

Clone this wiki locally