Skip to content

Speak JSON only? The buddycloud HTTP API can talk to you now

July 19, 2012

My last post about the buddycloud HTTP API was quite a long time ago (almost three weeks!). This has multiple reasons. One of them is that I had to write this semester’s exams in the last three days and thus didn’t have that much time between having to learn for them and going to University. (The semester has ended now, so no more University work from now on – yay!)

The other reason is that the next feature I planned to implement – the ability to long-poll the API server for real-time updates to channels – depends on a not-yet-implemented feature in the buddycloud XMPP component. Namely, it should be possible to temporarily subscribe to a channel to get update notifications even if you are not a follower of the channel. I started to implement this, but as Thomas aka Schnouki, who I am drafting this with (hey Thomas, thanks for helping me out!), is not available this week, I cannot currently continue this work sensibly.

Instead, I worked on something that multiple buddycloud core developers bugged me about in the last few weeks. (Here you are, Simon! :)) Previously, the API used JSON for several types of API requests such as getting subscriber lists or channel metadata, but the post streams themselves were only delivered as Atom feeds – that is, in XML form. The slightly awkward consequence of this is that you might need to do both XML and JSON processing when using the API. This might not be a problem for several use cases (in JavaScript, the XMLHttpRequest.responseXML attribute makes XML processing pretty easy actually), but often, one would rather like to have a simpler, JSON-only interface.

For such cases, I have sat down this week and implemented the possibility to get a JSON-serialized form of a channel’s posts. It doesn’t include everything the Atom version has – in fact, it’s pretty ad-hoc and downright primitive. It includes pretty much everything that most clients are interested in, though, like the items’ contents, who posted then, and which other post it relates to (if it is a comment).

Atom is still the default, but you can ask for JSON by including Accept: application/json into your request. For instance, this is how the latest two posts to topics@topics.buddycloud.org look when requested this way:

[
  {
    "id": "0a1ef625-8723-47f3-b6fe-d1dc89f242db",
    "author": "tuomas@buddycloud.org",
    "updated": "2012-07-17T20:17:00.818Z",
    "content": "Welcome!",
    "replyTo": "f0ecd09a-284b-41e6-9863-8214253b1aa3"
  },
  {
    "id": "4e60f61d-e87a-4ad8-a8d4-51b04094a56c",
    "author": "fahrertuer@buddycloud.org",
    "updated": "2012-07-17T15:25:53.987Z",
    "content": "coffee@topics.buddycloud.org\nFor all of us, who love their 1,3,7-trimethyl-1H-purine-2,6(3H,7H)-dione coming from the black brew"
  }
]

(I assume he “acct:” prefix in the two older posts’ “author” field comes from an earlier buddycloud server version.) You can also use this JSON format to post new items. For more details and some examples, see the HTTP API documentation. This feature is already deployed at api.buddycloud.org, so you can already play around with it if you like.

Another small thing I did was to slightly tweak the HTTP demo client. It now looks better and shows the viewed channel’s followers. Posting is still not implemented, though; this is for later.

Advertisements
Leave a Comment

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: