sanity please

I'm sure this tale of woe will be shared by many of my web development colleagues, it has to do with Facebook. As a web developer I have to pay a Facebook Tax, Facebook has an API (I think they might be up to their fourth API now) and they have 500 million people, and so management everywhere wants their product to integrate with Facebook. Here's the problem, Facebook fucking sucks at documentation.

There are as far as I can tell at least 4 competing technology stacks going on over at Facebook: FBML, Javascript SDK, Old REST API, and Graph API. There could be more, some of those might not be fully APIs and are just components, I'm not really sure. I've been reading the pages at the official documentation website for weeks now trying to wrap my head around this thing. Maybe it's just me, maybe I'm dense or something, but I can't seem to figure out what the fuck is going on or what I should be using.

Here's a great example, let's say you want to integrate Facebook Connect (if that's still a thing, I'm not really sure), but more succinctly you just want to allow users to sign in using Facebook as their identity provider. How are you supposed to do this. Well there is this section on Single Sign-On that looks promising. But then later on if you follow the link to learn more about the Graph API you will find a section about Authorization that will lead you to this page on Authentication which I think is showing you how to do the same thing, maybe.

The problem seems to be too many ways and pages explaining the same thing or slightly different things, I just want one canonical authoritative place to look that says, "This is the API you MUST use for Authentication." I don't think that is asking too much. But I'm sure once I finish my primer on OAuth 2.0 and figure out how the extended permissions works it will all be more clear.

The API could be forgiven for giving you more than one way to skin a cat, if it then gave you specific details on how this stuff actually works. Let's say I want to build a website that displays events and then let's people use my website to mark themselves as attending that event in Facebook, is that possible... I have no idea. Here's a section of the Graph API about Publishing data to Facebook and it might be in there somewhere, but I can't tell. I guess I'll have to play around with how this supposedly RESTful API works when I have some state, maybe if I've successfully negotiated an OAuth Secret Consumer Token UID then I can call /EVENT_ID/attending and that will mark me as attending the Event with EVENT_ID, it seems to make sense a little bit, but the extremely helpful description of "attend the given event" and the arguments of none make me have to play around to figure it out.

Seth Call is similarly frustrated and makes a very nice detailed case for why the Facebook API is so woefully inadequate. I couldn't agree more, and I hope that help is on the way.

The problem I'm running into now is frustration and discoverability. There doesn't seem to be a particular flow to these documents, they are just disparate documents hyperlinked together in no particular order. I'm new is there a tutorial or common use case section, maybe somewhere buried 9 links deep. If you are going to embrace and extend then at least have the common courtesy to make our lives easier as you try to take over the world.

Facebook seems to have too many developers working in the API space not communicating, the "Old" and "New" APIs overlap in some areas and miss each other in other areas, there's no definitive answer on when support will end for any of the "Old" APIs, is it safe to use the "Old" REST API for functionality the Graph API doesn't support or will they turn off the tap at some point. When trying to navigate through the documentation it just feels like they made someone do a braindump and didn't try to organize it in any fashion.

Well I'm going to head back in because with the draw of 500,000,000 potential users we can't afford not to pay the Facebook Tax, which is a real shame considering how shitty the Tax Code they published is.