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.

Oh, and that API is written in Go, it actually is running on my home machine... but the interfaces are mocked using internal data structures. That is... it's only missing the wiring to a database to be a live API.

And you might have noticed that I've focused on only 3 types within a forum whilst I test the API... I'll add things like classifieds, Q&A, reviews, articles, etc over time.

On the resources themselves:

GET /api/v1/resource ReadMany Reads a collection of resources
GET /api/v1/resource/{id} Read Reads a specific resource
PUT /api/v1/resource UpdateMany Updates a collection of resources
PUT /api/v1/resource/{id} Update Updates a specific resource
DELETE /api/v1/resource DeleteMany Deletes a collection of resources
DELETE /api/v1/resource/{id} Delete Delete a specific resource
POST /api/v1/resource Create Creates a new resource

Although DeleteMany obviously won't work in most cases (permission denied), though would work for /api/v1/notifications which would only ever be your notifications.

Got WSDL?

edit:

Have you chosen an auth mechanism for the put and get?
Could you be using 304 Not Modified as a response to some GETs?

Anyone else up for Hackathoning a traffic-thrifty Android app for Microcosm?

The API is JSON only this second, though I want to also offer XML and others eventually. No WSDL today... do you really want one? Really? I don't know anything that can generate them from Go interfaces, I'd have to write it by hand which is a PITA.

Auth mechanism is likely OAuth 2.0, using this lib should you be interested: https://code.google.com/p/goauth2/source/browse/oauth/oauth.go

Though auth suggests applications and permissions, and permissions makes me think about users and all of that about security, logging, rate-limiting, usage data... and whilst I know what approach I'm taking I want to get core data structure concepts right before addressing the cross-cutting concerns.

And yes, GET requests will vary by headers, be cached by Varnish, and may result in a 304 on cache hit and browser already having a copy.

It's way too early for an Android app... can I delay you until January?

What I'm looking for now is: This makes sense, I can navigate around the API and understand what exists and roughly how I'd call it.

Then: Are there any obviously massive things you might expect to be possible content-wise that you're not seeing? Are there any refinements to the resources that you'd propose?

Does it barspin?

Ah, by WSDL I was just implying some definition of the valid data returned by each of those methods, i.e. what's in the data: part.

As soon as the API is capable of listing threads and returning threads I'd like to get my hands dirty on a v0.1 whereby it would avoid fetching old unmodified posts, locally caching up to a few MB of post data, thread lists, whatever...

Yes, API specs are on their way... once it settles and I've written more I'll produce a set of documents for what it should look like, what to expect where, what params work, what to send me, etc.

The API is JSON only this second, though I want to also offer XML

Oh hell, I'll just do that now:
http://home.buro9.com/api/v1/microcosms.xml

Adding .json or .xml to the URL (as a file extension) will force the format to be one or the other.

Though if you ask for XML you will NOT get the status code in the XML as XML doesn't do JSONP callbacks and callbacks aren't supported either... you just get your XML.

Just browsing around the API and noticed what is probably a little typo (or a hole in my understanding of REST):

http://home.buro9.com/api/v1/microcosms

The third rel in "links" is a bit weird...

I see Json is involved. This whole thread makes Jason Murtle seem clear.

And if you looked at:
[code]
http://home.buro9.com/api/v1/
[/code]

You'd notice that 'comments' are now mocked on too.

Flow...

To render the home page of LFGSS you'd probably need to make 3 calls:
[code]
http://home.buro9.com/api/v1/site
http://home.buro9.com/api/v1/whoami
http://home.buro9.com/api/v1/notifications
http://home.buro9.com/api/v1/microcosms
[/code]

The first three do the following, you'd call them on every "page" of the web site, far less frequently for mobile clients:
site = returns high level info about the site including the site title and stats
whoami = returns basic user info for the logged in person, username and avatar
notifications = returns a list of notifications, date descending, indicating unread notifications

The only thing of interest is the call to:
microcosms = the forums that exist on this site

Assuming the user now navigated into a microcosm:
To render a microcosm (forum) listing you'd call the big 3 (site, whoami, notifications) and then:
[code]
http://home.buro9.com/api/v1/microcosms/1
[/code]

That will now return a list of all items (events, conversations, polls, etc) within that microcosm.

Assuming that an event was now clicked on the next page calls the big 3 and then:
[code]
http://home.buro9.com/api/v1/events/1
[/code]

This contains info on the event (what, where, when, how long, etc) as well as an array of comments (posts in vBulletin language) associated with the event.

The comments are all represented right now as ESI statements... that means Edge Side Include: [ame]http://en.wikipedia.org/wiki/Edge_Side_Includes[/ame]

Where it says:
[code]
"esi": "/comments/1"
[/code]

You will get the whole document that is at http://home.buro9.com/api/v1/comments/1 merged in-line inside the event document.

Which means a single call to the event detail would render all info for a whole page of the event thread including all of the event information and status.

Pagination params on the event ?limit=25&offset=50 now allow you to navigate through the comments on the event.

That's the flow... but it's all mocked right now, and I'll write some documentation very soon.

Just browsing around the API and noticed what is probably a little typo (or a hole in my understanding of REST):

http://home.buro9.com/api/v1/microcosms

The third rel in "links" is a bit weird...

Nope.

Rel will describe either self-referential relations:
[code]
this
next
prev
last
[/code]

Or external relations by API type so your code will know what to deal with:
[code]
/api/v1/site
/api/v1/microcosm
/api/v1/comment
/api/v1/event
[/code]

Unless you meant that I have mis-typed the values, in which case probable.

Fuck... late for Impetus Momentus... I'm out of here.

Does it barspin?

I see Json is involved. This whole thread makes Jason Murtle seem clear.

What is the meaning of this?

Is this thread public?
Are you giving away any commercially sensitive information to potential competitors?

As VB has pointed out before. Even with relevant information, he thinks it would take years for any competitors to get to where Microcosm is at now; years in which mc will have made further developments and be leaps and bounds ahead...

...IIRC.

You're right
VB/Velocio is not stupid

Has that cat got thumbs?

Auth mechanism is likely OAuth 2.0, using this lib should you be interested: https://code.google.com/p/goauth2/source/browse/oauth/oauth.go

OAuth 2.0 has only ever given me nightmares due to lack of any agreed standard way to implement or real wide spread community support.

http://hueniverse.com/2012/07/oauth-2-0-and-the-road-to-hell/

http://player.vimeo.com/video/52882780

This is now up again:
http://home.buro9.com/

Difference is that now most of the APIs write to the database, do sane things, use auth, and that it's up because we're now building the skeleton of the front-end that will sit in front of the API.

If anyone is interested in initial testing, let us know as we'll need to give you an access token.

that doesn't work for me.

Which could mean anything.

Does it not work in a connectivity way, or... well... what way doesn't it work for you?