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.

Nouns
allocation
property
metric
restriction
user
info
token
session
authorization
permission
batch
comment
friend
count
cookie
member
tag
url
handle
group
translation
link
string
message
thread
folder
note
notification
list
e-mail
page
fan
photo
album
profile
sms
stream
option
like
filter
status
video
limit Verbs
get
show
update
destroy
post
put
exists
verify
end
follow
leave
report
request
authorize
authenticate

Nouns
search
trend
status
timeline
mention
retweet
friend
follower
direct message
friendship
id
account
session
delivery device
color
image
profile
favorite
notification
block
spam
search
token
test

I made this list by combing through both services’ API documentation and extracting noun-like words and verb-like words from the names of resources or methods. Facebook count: 24 verbs, 43 nouns. Twitter count: 15 verbs, 24 nouns.

Here’s what I think these numbers mean.

Facebook manages many different kinds of content, and allows you to perform many different kinds of actions on that content, though the actions that you can perform on one kind of content are inconsistent with the actions you can perform on another. Twitter has fewer types of content, and a more consistent set of HTTP-like actions to perform on that content.

The Facebook API tends toward the baroque and insular, while the Twitter API tries its best to be a part of the web. In general, the Twitter API is much more straightforward.

I think this simplicity—this paucity of nouns and verbs—has been an important factor in Twitter’s widespread growth among both users and developers.

Developers can be confident that—even if Twitter’s API changes—they’ll still be doing mostly the same actions (getting, posting, updating) on mostly the same things (statuses, friendships, direct messages). Users know exactly how all the moving parts of Twitter work together, and are therefore better able to understand how a given application might augment that.

On Facebook, the opposite is true. User statuses, notifications, event invitations, feed stories, photos—they all have different interfaces and behave in different ways. Even long-time developers can’t keep track of how everything works together.

Interestingly, Facebook’s platform roadmap says that one of Facebook’s goals is to “focus [...] communication on the stream and Inbox,” which will make communication on Facebook feel much more like Twitter. I think this is a smart move—anything that simplifies the user’s model of how communication on Facebook works is a good idea, both for users and developers.