Data Store API documentation
From Facebook Developer Wiki
Contents |
[edit] BETA
[edit] Notices
- 10/01/09: Preliminary Ruby client for this: http://github.com/clararaubertas/Facebook-Data-Store-Ruby-API-Client
- 02/20/09: Note: Support for the Data Store API is temporarily disabled until we support user-level permissions. You can still make any call, but you must include your application secret.
- 01/08/09: Except for the User Preference API methods, all Data Store API methods have been disabled for desktop applications. This is to prevent a desktop client from accessing and manipulating data and schemas that don't belong to the user of the client. The preferences APIs are still available because they are authenticated by user sessions.
- 10/17/07: Preliminary object-oriented framework for Facebook's Data Store API: http://www.davidjarvis.ca/facebook
- 10/14/07: Please use http://bugs.developers.facebook.com/ for bug report and feature requests. Thanks!
- 10/14/07: PHP client library is ready to download at http://developers.facebook.com/clientlibs/facebook-platform.tar.gz
- 10/5/07: Complex data type bug is fixed now. We have changed to use JSON encoding for all lists and maps data store API uses. We think JSON is a lot easier than other encoding formats like XML. So, one can use these to pass in complex data types now:
[1, 2]
["a", "b"]
{ "1": "a", "2": "b" } // please make sure to use double quotes for both names and values
-
10/3/07: We found a bug with our complex data structure handling, and currently they may not work as expected. We will post an update when this is fixed.
[edit] Overview
Data Store API is mainly designed to help our platform application developers to quickly come up with a scalable storage solution that can keep up with rapid growth of their user base. Currently there is no plan or intention to charge people on normal usage. We will impose upper limit to ensure fair use of the service between different applications, and we will post the limit when we have it.
There are 3 groups of API functions:
- Specialized Tables: Since our goal is to simplify platform application development, we provide specialized and, more importantly, optimized table types that are commonly needed by different applications. Currently, there is only User Preference that's implemented. Developers are more than welcome to express their interest in what types of tables they want to have from us.
- Distributed Tables: We use "object type" throughout the entire API, but conceptually an object type isn't that much different from a distributed database table. "Distributed" is the key, since we really want to make sure data access can be scaled to millions of rows without degradation of performance. Having a large number of rows isn't uncommon to platform applications, since they normally grow exponentially when they become popular among Facebook users. Storing data in a distributed table upfront will ensure the ultimate success of such applications.
- Associations: The traditional database approach tends to use indices to help query speed. However, indexing a distributed table normally offers no performance gain, due to uncertainty where target objects are and the scalability requirement of not having centralized directory services. Associations are our way of providing fast lookups of objects without ANY centralized indices or parallel queries. It may take our developers some effort to think in the "association" way, but once this thought process is gone through, the final solution is normally scalable with great performance guarantee. Follow this link to read more about what an association is: data.defineAssociation.
Currently, only application developers can view and update object type and association definitions. Only end users of an application can view or update objects that are defined and created by the same application. There is no sharing between different applications, although Facebook objects are accessible through similar FQL interfaces.
[edit] User Preference API
Note: Desktop applications can call these 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 |
[edit] Object Data Definition API
Note: Desktop applications cannot call these 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 |
[edit] Object Data Access API
Note: Desktop applications cannot call these 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 value by a hash key |
| * data.removeHashKey | delete an object by its hash key |
| * data.removeHashKeys | delete multiple objects by their hash keys |
[edit] Association Data Definition API
Note: Desktop applications cannot call these 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 |
[edit] Association Data Access API
Note: Desktop applications cannot call these 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 |
