*UPDATE*: Carl Sjogreen, the lead of the platform PM team, commented below that positive changes are coming. All of us should hope he and his team succeeds!
Using the Facebook API is the one of the worst experiences as a developer I have ever had. This past week has been a real trial, and a true challenge to keep my energy and spirits up so that I remain efficient.
Whew, that’s off my chest. Let me stop with the bashing, and try to digest down what they are doing wrong in an effort to try and be constructive rather than purely inflammatory.
When you document your API, you have to at a minimum do the following:
- Define each method
- For each method, define inputs
- For each method, define outputs
- Describe the possible values for every input
- Detail possible error responses
- Detail how configurations outside the scope of the API call may affect your code.
- Performance limitations (rate limiting in the case of Facebook)
Facebook fails to come through on all of these points, even #1
I was trying to find some part of the documentation that would describe all Facebook-created dialogs that I can use, because I wanted to show a ‘friend finder’ equivalent to what is natively available in Facebook, but on my own website. I find FB.ui (a ‘Core Method’), look over the documentation for that method, which I see takes an argument called … ‘method’. Ok, fine, so FB.ui must actually be a class or package and not a method, but whatever. I’m already confused a little but no biggie.
So once I take a look to see what’s available in FB.ui…there are only two methods stream.publish and stream.share! That’s not much.
I back up to the parent of FB.ui (‘Core Methods’), click around every link I find there, do google searches, and look through the developer forum, but find no more UI-related methods.
I freaking knew it.
Anyway, I then zero in on fbml.dialog, because I vaguely know FBML has a lot of predefined tags made by Facebook that I could use to make my own UI. So I turn to the FBML documentation. The main page says this along the top now:
Note: We do not recommend FBML for new developers. If you aren’t already using FBML, you should instead implement your application within an
We will stop allowing new FBML applications, but will continue to support existing FBML tabs and applications. Instead, we recommend using IFrames.
But this is just a roadmap, and moreover, it’s the dubious Facebook roadmap. I decide I won’t worry about it, and try to figure out how to use fbml.dialog on my own. I know the only other option left for me is to post on the developer forums, but just the thought of doing so leaves me despondent.
In closing on documentation, searchability is terrible, navigation is terrible, the content is extremely thin and often wrong, and the developer forums are a wasteland of frustration.
If I’m going to use an API, I have to test it first, right? This is even more important with the Facebook API(s), since the documentation is so poor and the amount of issues you encounter with almost any API call ensures the only way to really know what the Facebook API will do is to simply use it.
Well, what if there were an API call that only worked with production code? That’s pretty limiting, especially in the face of all the other Facebook issues. It’s a bit chicken-and-egg to have to have production code act as your testbed, wouldn’t you say?
Well, unfortunately, any API call that has to do with the dashboard is subject to this limitation.
Side rant: what is the dashboard? Good luck finding a generic description in the API documentation as to what it is. You have to sift though forum posts and blog posts by Facebook to infer that the dashboard is an end-user’s left navigation. That’s the ‘dashboard’. I’d call it a left nav but hey, Dashboard sounds better, right?
Anyway, you can see all dashboard API methods here if you scroll down. Oh but by the way, don’t use publishActivity. From scraping the forums for hours for anything related to the dashboard, I can tell you it doesn’t work because other users have already been burned by using just the documentation.
Back to testability. I tried out dashboard.addNews, which should make a news item show up in my stream … according to the documentation (are you starting to feel a description in the docs don’t count for a lot?). Here is the relevant description of dashboard.addNews:
Calling this method appends the news items included in this call to the news stream. Facebook displays up to two news items (either personal, global, or both) at a time for a given application, starting from the two most recently added.
Great! Just what I needed. So I take the time to create a test application, create test users, and use dashboard.addNews successfully–at least, as far as the response of the API call is concerned. But when I check the test user’s account, there is strangely no news showing for the application. So back to the developer forums to look for similiar problems.
I find this post, which seems to imply the application must be bookmarked and submitted to the directory–or doesn’t require being in the directory depending on which user you believe in the post. Also, this bug referenced in the forums simple says that ‘sandboxed’ applications can not be used with the dashboard, so I made sure that my application was not configured as sandboxed (which makes no sense for a test application but you do what you gotta do).
I found a few other forum posts talking about bookmarking, so I tried that out first when debugging. But apparently the way you bookmark applications recently changed, confusing me a while how I was supposed to do this. Long story short is, I got my application bookmarked, and if you can imagine, addNews still didn’t work.
So I posted on their developer forum. After 24 hours, no responses yet. I could wait, but since most posts don’t get responses on the forums, I have to assume I won’t get one.
So moving on, I thought, well, I never tried submitting my application to the directory. So I found the link for that (which is not in the configuration of the app where I spent a few minutes looking first), clicked it, and was told that I have to have at least 5 users of the application.
Wow. So just to test the idea if being submitted in the directory is important, I have to somehow get 5 users associated with my application? I had actually signed up four test users with the application, but the application reported that I only had a grand total of 0 users.
I eyeball another application I made for a different company, which had more than 5 users but was never published because it didn’t need to be found via the Facebook directory. But if I could just try out dashboard.addNews with this application, maybe I’d have an answer!
Since I’m luckily a co-founder of this other company, I said the heck with it, I’ll publish it. And so I did. After 4 hours waiting for it to be approved, I then tried dashboard.addNews with this application instead of my test application.
And, this time, I can’t seem to successfully bookmark it.
If I make progess on this, I’ll update my developer forum post at least with my solution.
UPDATE: I can’t play with the configuration of my application so that I can continue debugging because of a rather major bug affecting all applications for the past 24 hours or so.
In closing on testability, there are other reasons that it is difficult to test Facebook applications, but I think the example here is good enough.
NO RESPONSE TO SERIOUS ISSUES
I’ll zero in on two.
ORDER BY AND LIMIT in FQL
FQL allows developers to make queries to fetch results in a SQL-like way. A while back (I think June 2009), Facebook added ORDER BY and LIMIT to the language. But it is horribly broken. If you like, you can try to discern what’s wrong with ORDER BY and LIMIT by navigating through the NEW and UNCOMFIRMED bugs opened here: Note that almost all bugs are NEW and UNCONFIRMED, so don’t just assume that a new bug is actually new in terms of age.
Please, don’t bother looking through their bug tracker. I’ll tell you what’s wrong with ORDER BY AND LIMIT. Basically, it seems Facebook has a sharded database backend, and simply proxies your ORDER BY and LIMIT to it’s back end data stores, meaning each sharded data store, which only has a partial set of the overall data, can’t possibly do this correctly since LIMIT will cause the sharded data store to paginate into it’s own data, limiting the data you get back artificially and incorrectly.
Protip: If you use ORDER BY/LIMIT, you should set the LIMIT to the max of 1000, and just get as much as you can. Don’t ever try to paginate with FQL.
UPDATED_ON/CREATED_ON CORRUPTED BY USING ORDER BY AND LIMIT
I found that, for some facebook fan pages, that if I specified ORDER BY, LIMIT, then the created_on and updated_on fields returned are completely incorrect. I opened a bug on it in February 2010, and nearly 7 months later, the state of my bug was marked as duplicate of another bug.
Oh boy, 7 months and I can fix my application! Yaaaah!
Hold on, wait, what’s this? The other bug is marked as unconfirmed still. Oh. It was opened in August 2009. So it’s been over a year. I guess you just have to be patient.
Hey, but surely they’d warn in their documentation that ORDER BY and LIMIT are broken?
Not here either.
CONSTANTLY CHANGING API
If you are going to constantly change your API, deprecate things, remove methods, etc, you had better be fixing major issues along the way.
But everything indicates that the API(s) only get more confusing and more broken, and migrations are done usually rather brutally. You can search through the developer forum if you want to corroborate.
A side-effect of a constantly changing API is that you aren’t sure what you should be using versus what’s fallen out of favor.
Consider the the reasonably new Open Graph API. It lets you read and modify a great deal of data found within Facebook. You could already do this with the Old REST API, but this API is easier!! and better!!
As a developer who has already been through the onerous task of learning the REST API, this new API was only bad news. I don’t care to relearn, and I don’t want to rewrite existing code. But I feel compelled to. After all, the REST API is now old.
But I can’t do certain things with the shiny new Open Graph API. For instance, the dashboard API methods in the Old REST API (I can’t get over the fact they call it OLD. It drives me crazy every time I read it) are not in the Open Graph API. So now, I have to use the Open Graph API if I want to be modern and in-line with Facebook, but I absolutely have to use the REST API if I want to use the dashboard (you might be laughing to yourself if you’ve noticed I’m worried about the Dashboard API when I can’t even get it to work).
The removal of application notifications was a good example of this too. The dashboard API is actually a replacement for the old notification API. I’m not sure why they couldn’t leave the old notification API in place, and just change the actual behavior, but apparently they had to build a newer and more broken API.
I’m not alone by the way in my frustration.
Facebook, get it together. It’s not hard to have good documentation or good customer service, but it does require internal prioritization. Stop not caring about developers.