I’m a complete and total bigot. Unmitigated, complete, total bigot. The web sucks. And web APIs suck too. Especially when the documentation is non-existant or confusing or wrong. That sets me off.
You see, I hate shit. It smells. I don’t smear shit all over the walls in my house, and it kind of pisses me off when companies smear techno-shit all over my computer.
But there is a point to this all. And some real substance. Below addresses a retarded problem that just shouldn’t arise.
So let’s take the Facebook API and a simple example for uploading a photo to an album. Seems pretty simple, eh? Hardly.
This is the page for the Facebook Graph API: http://developers.facebook.com/docs/reference/api/
In there, you’ll see a line like this:
Photo Albums: https://graph.facebook.com/me/albums?access_token=…
Click that link and it will take you to a page of JSON that lists all of the albums you have for your photos on Facebook. The JSON looks something like this:
{
"data": [
{
"id": "12345678901234567",
"from": {
"name": "Ryan Smyth",
"id": "0987654321"
},
"name": "Some album name here",
"description": "Some album description here",
"link": "http://www.facebook.com/album.php?aid=123456&id=0987654321",
"cover_photo": "01234567898765432",
"privacy": "everyone",
"count": 53,
"type": "normal",
"created_time": "2011-01-02T01:16:33+0000",
"updated_time": "2011-02-03T14:49:02+0000"
},
{
"id": "01234567890123456",
"from": {
"name": "Ryan Smyth",
"id": "0987654321"
},
"name": "Another album name here",
"link": "http://www.facebook.com/album.php?aid=234567&id=0987654321",
"cover_photo": "12345678909876543",
"privacy": "custom",
"count": 1,
"type": "normal",
"created_time": "2011-01-23T11:43:40+0000",
"updated_time": "2011-04-23T11:45:21+0000"
},
…
Simple enough. JSON is basically crippled, wounded, lame, retarded XML, so it should be pretty easy.
Well, there’s an “id” field there, and this is the albums, so, that must be the album ID, right? Hardly…
I really have no clue WTF that “id” field is, but it isn’t the ID for the album.
After farting around and wasting massive amounts of time experimenting with every conceivable permutation of the path variable, e.g. “/me/albumid/photo/”, and just generally getting jack-all done, I finally figured out that the actual album ID that you need to post to is in the “link” value as the “aid” variable’s value. So you need to divine the actual variable name, i.e. “aid”, and set that to the proper value.
So the variable name and the proper value are both obfuscated. Huh? Like, really… WTF?
Just how bloody hard would it be to put that in the docs? Oh, that’s right… Web APIs don’t have docs… Duh~? How stupid of me.
So, instead of putting the ID in the “id” field, which would make sense, I now need to muck around in the “link” field to extract the ID for the album.
That nonsense would never fly anywhere else except in the PHP and web world where sanity doesn’t rule the day.
There must be some kind of reasoning there somewhere, but I just can’t see it for the life of me. Maybe I should drop more acid…
Anyways, I hope my babbling rant has helped to solve some pain for someone. I’ll try to remember to post some code once I’m done farting around with it.
Grrr. Argh.
Ryan
