The Facebook API battle/disaster night

I thought it would be fairly simple...

I had worked on a Facebook iframe application once before, and I remembered that the addition of requiring Facebook login and then being able to render XFBML components was not very complicated at all.  It was a matter of pasting in some code in a few different places, and magically, the page would request you to log in and add the application, and then it could show you your Facebook picture and name.  (By the way: FBML = Facebook Markup Language, and XFBML is the version you can use on off-site pages, i.e. your pages in an iframe, or on Connect app pages.)

Well, there I was, just over a year later.  I began delving into the wiki/documentation on authentication etc., and what I began to realize is that everything seemed to be in transition.  There was this new "graph API", and OAuth authentication, and a new Javascript API -- or at least, these all appear to be new, based on the look of the pages and what I could gather from the descriptions.

I really only wanted to be able do 3 things: require login and authentication of the app, pull/display users' names, and pull/display users' profile picture thumbnail.

Many long hours of confusion later, I had gone through stages something like this:

1. using the wrong new stuff (a PHP API which I now think is supposed to be for Connect apps?);
2. trying to use the old PHP library, cross-domain receiver file, XFBML, and iframe resizing... I don't even remember what didn't work in this combination, but some piece didn't;
3. trying to combine the old PHP library and XFBML paste-in code with some of the newer stuff, I think? I don't even remember;
4. attempting to manually implement the OAuth redirection cycle (things like obtaining a key and this and that), which actually almost worked...;
5. deciding to give up on making this an iframe application that's actually within the Facebook chrome, and instead, switching it over to a Connect app, using the easy authentication/login via the new Javascript API and all of which is luckily still compatible with XFBML.

...wow.  It was a long, tiring, frustrating struggle.  Much of it was due to over-documentation, if you will, and a lack of clarity in terms of marking pages regarding at which level of API/platform transition the information and code on that page would still be relevant and functional.


And now for the bombardment of a list of links.  Here are some of the many Wiki pages/sections I tried to use to figure this out...

(Note: seems like they are really in transition currently - some of the links may not work or will give a message saying the content is moved/updated)


New (pages are in the theme of the new documentation)

Overview guide to apps (new)

Authentication (new)

Graph API (new)

JavaScript SDK (new)

Old REST API - apparently the precursor to the new Graph API


Old, but seems to still apply / be compatible with new stuff

XFBML (including tag list)


Old, and seems to not apply / not be compatible with new stuff

API (old?)

PHP (old?)

FB_RequireFeatures (old?) - for dynamically loading components of the JS API (via FeatureLoader.js.php)

Authorization and Authentication for Canvas Page Applications on Facebook - matches with the old(?) PHP library

Extended Permissions

Connect/Setting up your site - including XFBML rendering (but uses the FeatureLoader.js.php)