Skip to content
Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
259 lines (191 sloc) 4.55 KB

API

[TODO: Too tired to complete the docs. If you feel like contributing, please take a look at the routers and send a pull-request.]

Roles

Valid roles are "admin" and "member".

Authentication

Find your auth token on your account settings page. If your token is 1n2jjvsns, pass the auth token as a header Authorization: 1n2jjvsns for the API request.

Using curl for example, to get a list of rooms,

curl -XGET http://example.com/api/rooms -H 'Authorization: 1n2jjvsns'

Your access to certain API calls depends on the role of your account.

Request body

Request body must be encoded in JSON for all POST and PUT requests.

Available APIs

Users

Create a user

POST /api/users

Request body example:

{
  "user": {
    "name": "John Doe",
    "email": "user@example.com",
    "password": "password",
    "role": "member"
  }
}

Modify a user

PUT /api/users/:user_id

{
  "user": {
    "name": "John Doe",
    "email": "user@example.com",
    "password": "password",
    "role": "member"
  }
}

Delete a user

DELETE /api/users/:user_id

Rooms

Create a room

POST /api/rooms

{
  "room": {
    name: "Example"
  }
}

Modify a room

PUT /api/rooms/:room_id

{
  "room": {
    name: "New room name"
  }
}

Delete a room

DELETE /api/rooms/:room_id

Active users in a room

GET /api/rooms/:room_id/users

You must be active in a room ("joined") to access it's user list.

TODO example body

Messages

Post a message to a room

POST /messages

Request body:

{
  "message": {
    "room_id": 1,
    "user_id": 2,
    "body": "Hey guys, what's up?",
    "type": "text"
  }
}

Response body:

{
  "message": {
    "id": 80,
      "room_id": 1,
      "user_id": 2,
      "body": "Hey guys, what's up?",
      "type": "text",
      "created_at": "2014-04-07T08:28:48Z"
  }
}

Get messages in a room

GET /messages/:room_id

By default lists the most recent 20 messages in a room.

In order to get a room's history or get future messages, you can pass any one of the following params:

  • before - ID of a message, before which you need the 20 previous (older) messages. Use this to fetch history.
  • after - ID of a message, after which you need the next (newer) 20 messages. Use this to poll for new messages.
{
    "messages": [
        {
            "id": 8,
            "room_id": 1,
            "user_id": 2,
            "body": "Hey guys!",
            "type": "text",
            "created_at": "2014-03-30T12:09:11Z",
            "user": {
                "id": 2,
                "name": "Jurre",
                "role": "member",
                "archived": false
            }
        },
        {
            "id": 9,
            "room_id": 1,
            "user_id": 2,
            "body": "What's up!?",
            "type": "text",
            "created_at": "2014-03-30T12:17:22Z",
            "user": {
                "id": 2,
                "name": "Jurre",
                "role": "member",
                "archived": false
            }
        }
    ]
}

Room User States

Get room states

GET /api/room_user_states

Returns the user's states of rooms (joined/unjoined, last pinged at, etc), along with the room details (only name of the room for now).

TODO

Join or leave rooms

PUT /api/room_user_states/:room_user_state_id

The room_user_state_id is the user's state's ID in a room. It is not the room ID. The user's states for rooms can be fetched as mentioned in the previous request

Set joined to true to join a room, or set false to leave it.

TODO

Sessions

Sign in

POST /api/sessions

Request body:

{
  "email": "you@example.com",
    "password": "correct horse battery staple"
}

Response body:

{
  "user": {
    "id": 1,
      "name": "You",
      "role": "admin",
      "email": "you@example.com",
      "auth_token": "aa23e8a5-c9d1-4656-bee0-e30807177e0d"
  }
}
You can’t perform that action at this time.