decontextualize

Last October I undertook a “lexical analysis” of the Twitter and Facebook APIs. Twitter came out on top in that analysis. I concluded that Twitter’s “simplicity … has been an important factor in [its] widespread growth among both users and developers” while Facebook’s “baroque and insular” API makes it impossible for users and developers to “keep track of how everything works together.” Facebook’s been promising changes for a while, and change has indeed arrived, in the form of the new Graph API. So how does the Graph API compare, lexically, to Twitter? Here’s a revised analysis. (Spoiler: things are looking much better for Facebook.)

The tally: the Twitter API holds steady with 26 nouns and 15 verbs. The Graph API, meanwhile, has 35 nouns* and 3 verbs—a tremendous improvement on Facebook’s old (so-called) REST API, which has 43 nouns and 24 verbs. The Twitter API and Facebook’s REST API average around 1.7 nouns per verb; the Graph API has almost 12 nouns per verb. What’s especially interesting? The Graph API has managed to sidestep any verbs that aren’t HTTP methods.

The Graph API is a big deal, and an important step forward for Facebook. Here are a few reason I think that’s the case.

First of all, the Graph API is dead simple, especially compared to Facebook’s old REST API. Just as an example: the old API has (by my count) seven nearly synonymous verbs (set, create, add, register, upload, send, publish) that all essentially mean “add content for a user.” These verbs aren’t interchangeable; each works with only a subset of nouns (or even just a single noun). Each verb has idiosyncratic behaviors, arguments and error messages. The Facebook REST API is, in short, a mishmash of conflicting conceptual models. It’s tough to get a handle on all of it.

Not so with the Graph API. Every resource has exactly the same interface. Once you understand what each noun is, it’s easy to understand how to manipulate it—there are only three possible verbs, after all!

The complexity of the REST API necessitated a client library to perform even very simple operations. The Graph API, on the other hand, is so simple, I think that most developers won’t even use a library at all—it’s easier to just hit the URLs directly. Simply put: if you know how to make HTTP requests, you know how to use the Graph API.

That’s the second thing that makes the Graph API so important—it’s the web. The Graph API isn’t just a bunch of function calls for retrieving information; it’s a set of URLs to representations of the data itself. The data is all in JSON format, so it’s easy for browsers to consume it directly. Image URLs return the images themselves, so they can be thrown right into img tags without an intermediary API call. Most importantly, the resources returned from the Graph API are hypermedia: they include URLs to related resources. An example (from the documentation):

{
   "name": "Facebook Developer Garage Austin - SXSW Edition",
   "metadata": {
      "connections": {
         "feed": "http://graph.facebook.com/331218348435/feed",
         "picture": "https://graph.facebook.com/331218348435/picture",
         "invited": "https://graph.facebook.com/331218348435/invited",
         "attending": "https://graph.facebook.com/331218348435/attending",
         "maybe": "https://graph.facebook.com/331218348435/maybe",
         "noreply": "https://graph.facebook.com/331218348435/noreply",
         "declined": "https://graph.facebook.com/331218348435/declined"
      }
   }
}

The URLs are right there in the document, meaning that you don’t have to know anything else about how the Graph API works in order to get information related to a resource. Pretty slick. It’s an idea that (I think) every web API should incorporate.

There are, of course, a few factors that mitigate my enthusiasm for the Graph API. First off, it doesn’t quite model the entirety of Facebook’s functionality yet—notably, there aren’t any resources (so far) representing Facebook applications themselves. There are also privacy concerns that need to be addressed (for example, event listings).

Overall, though, the Graph API is beautifully constructed. It’s just as robust as the Facebook’s old API, but simpler, more convenient, and easier to integrate. As a developer (and programming instructor), my opinion has always been that Twitter’s main advantage over Facebook is its developer-friendly API. The Graph API has the potential to erase that advantage.

* There are a number of verb-like words and verb participles in the Facebook “noun” list. I classify them as such because, to my eye, they’re clearly presented in the API documentation as things you can act on, rather than actions you can take. For example, attending means “users who are attending something,” and acting on that resource allows you to fetch or manipulate that list of users.