API v2

This is page that captures the first sketch of the next version of JabbR API.

Principles

RESTful

Without getting into a debate about what's REST and what's RESTful, the API should attempt to follow REST architecture pattern where practical. An example of deviation from that could be content negotiation as it is implemented right now. We only foresee supporting JSON for this API, so in order to be able to see the response in the browser, we disregard Accept: header and just JSON anyway (as opposed to returning 400: Bad Request).

Discoverable

The API should be fairly discoverable, i.e. you should be able to arrive at the api endpoint and navigate your way around by following links (HATEOAS constraint of REST).

JSONP Support

JSONP is mentioned here because it imposes certain constraints on the payload - e.g. having to mirror response code and text status in the payload. This is necessary as browsers do not propagate the status codes when an API call is made via a script tag. These will only be available on JSONP calls, however this means that in order for JSONP and JSON payloads to be consistent, the payload has to be an object (rather than array, for example).

API

In order to simplify the endpoint address, we'll use /api, it is different from /api/v1 and will be more stable as well.

API "Front page"

GET /api

HTTP/1.1 200 OK
Content-Type: application/json

{
  "auth": {
    "janrainAppId": "appId",
    "authUri": "http://jabbr.net/Auth/Login.aspx"
  },
  "roomsUri": "http://jabbr.net/api/rooms/general-chat"
}

Rooms List

GET /api/rooms

HTTP/1.1 200 OK
Content-Type: application/json

{
  "rooms": [
    {
      "name": "general-chat",
      "roomUri": "http://jabbr.net/api/rooms/general-chat",
      "messagesUri": "http://jabbr.net/api/rooms/general-chat/messages",
      "owner: "donkeykong"
    },
    {
      "name": "meta",
      "uri": "http://jabbr.net/api/rooms/meta",
      "messagesUri": "http://jabbr.net/api/rooms/meta/messages",
      "owner: "laracroft"
    }
  ]
}    

Messages

GET /api/rooms/{room}/messages

HTTP/1.1 200 OK
Content-Type: application/json

{
  "messages": [
    {
      content: "Hello",
      username: "test",
      when: "2012-05-16T13:34:24.4408871+00:00"
    },
    {
      content: "world",
      username: "test",
      when: "2012-05-16T13:34:24.4408871+00:00"
    },
  ]
}