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

Authentication

Authenticating into the API is done with an API key. API key can be exposed through UI for logged in users. This can either be a separate page that allows creation of multiple keys or as a chat command. I think the API should accept jabbrstate cookie if API key is not provided, with rate limits applied to the whole account, regardless of API key being used.

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.

URL Parameters that can be used on any request:

format

Output format. Supported values are:

• json
• jsonp

Example: http://jabbr.net/api?format=json

apikey

Your API key.

Example: http://jabbr.net/api?apikey=lkjsdf90782345ksjdh230

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/{room_csv}

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"
    }
  ]
}   

room_csv is a comma separated list of rooms, this part of the URI is optional.

Messages

GET /api/rooms/{room_csv}/messages

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

{
  "general-chat" : {
    "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"
      },
    ]
  },
  "meta" : {
    "messages": [
      {
        content: "IQueryable sucks",
        username: "test",
        when: "2012-05-16T13:34:24.4408871+00:00"
      },
      {
        content: "RavenDB FTW",
        username: "test",
        when: "2012-05-16T13:34:24.4408871+00:00"
      },
    ]
  }
} 

room_csv is a required part of the URI, must specify at least one.