I learned about the Facebook Data Store API yesterday from a post by Marc Canter. The API is intended to meet the storage needs of developers building widgets applications on the Facebook widget platform. Before we decide if the API meets the needs of developers, we need to list what these needs are in the first place. A developer building a widget or application for a social network’s widget platform such as a gadget for Windows Live Spaces or an application for the Facebook platform needs to store

  1. Static resources that will be consumed or executed on the client such as images, stylesheets and script files. Microsoft provides this kind of hosting for gadget developers via Windows Live Gallery. This is all the storage needed for a gadget such as GMT clock.
  2. User preferences and settings related to the gadget. In many cases, a gadget may provide a personalized view of data (e.g. my Netflix queue or the local weather) or may simply have configuration options specific to the user which need to be saved. Microsoft provides APIs for getting, setting and deleting preferences as part of it’s Web gadgets framework. My Flickr badge gadget is an example of the kind of gadget that requires this level of storage.
  3. The application’s server-side code and application specific databases. This is the equivalent of the LAMP or WISC hosting you get from a typical Web hosting provider. No social networking site provides this for widget/gadget developers today. The iLike Facebook application is an example of the kind of application that requires this level of “storage” or at this level it should probably be called app hosting.

Now that we have an idea of the data storage needs of Web widget/gadget developers, we can now discuss how the Facebook Data Store API measures up. The API consists of three broad classes of methods; User Preferences, Persistent Objects and Associations. All methods can return results as XML, JSON or JSONP.

It is currently unclear if the API is intended to be RESTful or not since there is scant documentation of the wire format of requests or responses. 

User Preferences

Object Definition methods
* data.setUserPreference update one preference
* data.setUserPreferences update multiple preferences in batch
* data.getUserPreference get one preference of a user
* data.getUserPreferences get all preferences of a user

These methods are used to store key value pairs which may represent user preferences or settings for an application. There is a limit of 201 key<->value pairs which can be stored per user. The keys are numeric values from 0 – 200 and the maximum length of a preference value is 128 characters. 

Persistent Objects

Object Definition methods
* data.createObjectType create a new object type
* data.dropObjectType delete an object type and all objects of this type
* data.renameObjectType rename an object type
* data.defineObjectProperty add a new property
* data.undefineObjectProperty remove a previously defined property
* data.renameObjectProperty rename a previously defined property
* data.getObjectTypes get a list of all defined object types
* data.getObjectType get detailed definition of an object type

Developers can create new types which are analogous to SQL tables especially when you consider terminology like “drop” object, the ability to add new properties/columns to the type and being able to retrieve the schema  of the type which are all more common in relational database world than in object oriented programming.


Object Manipulation methods
* data.createObject create a new object
* data.updateObject update an object's properties
* data.deleteObject delete an object by its id
* data.deleteObjects delete multiple objects by ids
* data.getObject get an object's properties by its id
* data.getObjects get properties of a list of objects by ids
* data.getObjectProperty get an object's one property
* data.setObjectProperty set an object's one property
* data.getHashValue get a property value by a hash key
* data.setHashValue set a property value by a hash key
* data.incHashValue increment/decrement a property valye by a hash key
* data.removeHashKey delete an object by its hash key
* data.removeHashKeys delete multiple objects by their hash keys

This aspect of the API is almost self explanatory, you create an object type (e.g. a movie) then manipulate instances of this object using the above APIs. Each object can be accessed via a numeric ID or a string hash value. The object’s numeric ID is obtained when you first create the object although it isn’t clear how you obtain an object’s hash key. It also seems like there is no generic query mechanism so you need to store the numeric IDs or hash keys of the objects you are interested in somewhere so you don’t have to enumerate all objects looking for them later. Perhaps with the preferences API?


Association Definition methods
* data.defineAssociation create a new object association
* data.undefineAssociation remove a previously defined association and all its data
* data.renameAssociation rename a previously defined association
* data.getAssociationDefinition get definition of a previously defined association
* data.getAssociationDefinitions get definitions of all previously defined associations

An association is a named relationship between two objects. For example, "works_with" could be an association between two user objects. Associations don't have to be between the same types (e.g. a "works_at" could be an association between a user object and a company object). Associations take me back to WinFS and son of WinFS Entity Data Model which has a notion of a RelationshipType that is very similar to the above notion of an association. It is also similar to the notion of an RDF triple but not quite.

Association Manipulation methods
* data.setAssociation create an association between two objects
* data.setAssociations create a list of associations between pairs of objects
* data.removeAssociation remove an association between two objects
* data.removeAssociations remove associations between pairs of objects
* data.removeAssociatedObjects remove all associations of an object
* data.getAssociatedObjects get ids of an object's associated objects
* data.getAssociatedObjectCount get count of an object's associated objects
* data.getAssociatedObjectCounts get counts of associated objects of a list of objects.
* data.getAssociations get all associations between two objects

All of these methods should be self explanatory. Although I think this association stuff is pretty sweet, I’m unclear as to where all of this is expected to fall in the hierarchy of needs of an Facebook application. The preferences stuff is a no brainer. The persistent object and association APIs could be treated as a very rich preferences API by developers but this doesn’t seem to be living up to their potential. On the other hand, without providing something closer to an app hosting platform like Amazon has done with EC2 + S3, I’m not sure there is any other use for them by Web developers using the Facebook platform.

Have I missed something here?

Now playing: UGK - International Players Anthem (feat. Outkast)