API mockup

I've drafted a mockup of an API that right now (this instant) is hosted on my home machine:

http://home.buro9.com/

I've tried to balance discovery, pragmatic use, and a sensible RESTful structure that should be predictable and fairly intuitive.

Regarding the structure of the data, you should imagine that this API is available per site on the platform... so it would appear at https://lfgss.microcosm.app/ and also at https://glasgowfgss.microcosm.app/ and as such, once CNAMEd, would appear at www.lfgss.com and www.glasgowfixedgear.com respectively.

A version of the API that appears at api.microcosm.app will return results from ALL sites (but filtered according to global privileges), but the primary usage idea is that a user adds one or more Microcosm sites to their mobile client (or whatever) and that client talks to the domain specific API for 90% of the time as most users will only ever add a single or a very few sites.

The API will be used by the web site, whatever the web site can do the API must be able to do, so any clients that may exist have the potential to have full feature parity.

Data structure wise if you can read this you'll get it:

{site: [microcosm: [conversations, events, polls]]} < all of these also have activity

That is, a site contains one or more microcosms, and a microcosm contains things like conversations, events, polls, etc.

{site: [user: [notification]]}

That is, a site has a load of users, who all may have zero or more notifications (read or unread).

And you can always find out who you are (from an API auth perspective) by asking whoami

If an interface is plural, such as http://home.buro9.com/api/v1/events then you can reasonably expect that you can operate on singular instances http://home.buro9.com/api/v1/events/1

Regarding the API itself, all responses take the form:
[code]
{

"context": "",
"status": 200,
"data": null,
"errors": null

}
[/code]

Where context can be passed in via ?context= and assists with async callbacks by clients.

You can do JSONP callbacks by adding ?callback=functionName

Status is helpful if you are doing JSONP as you will want to return HTTP 200 even with an error, so the correct error will appear in the status field

For example, JSONP call that resulted in a 404 would never be processed, but you can add ?always200 to the querystring, forcing HTTP 200 (so JSONP is processed) and the status value will be 404 so that you can handle not found.

data is always the actual thing you want from the API.

errors is a string array of anything that has gone wrong. You should always check it isn't null.

Where pagination is implied, the param would be ?limit=10&offset=50 to fetch 10 records starting at the 50th. Most pages default to 25 records and the offset is 0 by default.