API

The article contains extended documentation about the Facebook API. With the API, you can add social context to your application by utilizing profile, friend, Page, group, photo, and event data.

[hide]

REST Interface

The API uses a REST-like interface. This means that our Facebook method calls are made over the internet by sending HTTP GET or POST requests to the Facebook API REST server (http://api.facebook.com/restserver.php) . Nearly any computer language can be used to communicate over HTTP with the REST server.

Note: If you manually form your HTTP POST requests to Facebook, you must include the request data in the POST body. In addition, you should include a Content-Type: header of application/x-www-form-urlencoded.

API Results and Localization

API results get returned in localized formatting, when such formats exist (for example, the user's gender). Namely, all requests made through restserver.php will obey the following:

If the current user is browsing Facebook in a non-US English locale, then the results of the API queries will return the user's locale only if your application has been listed as "published" from the Translations Admin Panel (http://www.facebook.com/translations/admin/dashboard.php?app=), or if they are allowed to see translations in progress for your application (see Translating Platform Applications for details). Otherwise, it will be returned with US English formatting.
If the user is in the US English locale, results will be returned as expected.
Both 1+2 can be optionally overridden, by adding the &locale parameter to either the GET or POST params for a restserver.php request. For a list of valid locales, please checkFacebook Locales.

API Methods

The Facebook RESTful API is organized into the following types of methods:

Administrative Methods

Use these methods to administer your applications and their users.

admin.getAllocation: Returns the current allocation limit for your application for the specified integration point.
admin.getAppProperties: Returns values of properties for your applications from the Facebook Developer application.
admin.getMetrics: Returns specified metrics for your application, given a time period.
admin.getRestrictionInfo: Returns the demographic restrictions for the application.
admin.setAppProperties: Sets values for properties for your applications in the Facebook Developer application.
admin.setRestrictionInfo: Sets the demographic restrictions for the application.
admin.banUsers: Prevents users from accessing an application's canvas page and its forums.
admin.unbanUsers: Unbans users previously banned with admin.banUsers.
admin.getBannedUsers: Returns the list of users who have been banned from the application.
application.getPublicInfo: Returns public information about a given application (not necessarily your own).
batch.run: Execute a list of individual API calls in a single batch.
data.setCookie: Sets a cookie for a given user and application.
fbml.setRefHandle: Associates a given "handle" with markup (like FBML or JavaScript) so that the handle can be used within the fb:ref tag.
intl.getTranslations (BETA): Returns an array of strings from your application that you submitted for translation. This call returns the original native strings, the best (or all) translations of native strings into a given locale, whether the string has been approved, and by whom.
intl.uploadNativeStrings: Lets you insert text strings into the Facebook Translations database so they can be translated.
links.getStats: Returns information about one or more Facebook Share implementations.
liveMessage.send: Sends a "message" directly to a user's browser, which can be handled in FBJS.
notifications.markRead: Marks one or more Facebook notifications as read.

Login/Auth Methods

auth.createToken: Creates an auth_token to be passed in as a parameter to login.php and then to auth.getSession after the user has logged in.
auth.expireSession: Expires the session indicated in the API call, for your application.
auth.getSession: Returns the session key bound to an auth_token, as returned by auth.createToken or in the callback URL.
auth.promoteSession: Returns a temporary session secret associated to the current existing session, for use in a client-side component to an application.
auth.revokeAuthorization: If this method is called for the logged in user, then no further API calls can be made on that user's behalf until the user decides to authorize the application again.
auth.revokeExtendedPermission: Removes a specific extended permission that a user explicitly granted to your application.

Data Retrieval Methods

comments.get: Returns all comments for a given xid posted through fb:comments. This method is a wrapper for the FQL query on the comment FQL table.
data.getCookies: Returns all cookies for a given user and application.
fbml.refreshImgSrc: Fetches and re-caches the image stored at the given URL.
fbml.refreshRefUrl: Fetches and re-caches the content stored at the given URL.
fql.query: Evaluates an FQL (Facebook Query Language) query.
fql.multiquery: Evaluates a series of FQL (Facebook Query Language) queries in one call and returns the data at one time.
friends.areFriends: Returns whether or not each pair of specified users is friends with each other.
friends.get: Returns the identifiers for the current user's Facebook friends.
friends.getAppUsers: Returns the identifiers for the current user's Facebook friends who have authorized the specific calling application.
friends.getLists: Returns the identifiers for the current user's Facebook friend lists.
friends.getMutualFriends: Returns the identifiers for the requested users' Mutual Facebook friends.
groups.get: Returns all visible groups according to the filters specified.
groups.getMembers: Returns membership list data associated with a group.
links.get: Returns all links the user has posted on their profile through your application.
message.getThreadsInFolder (BETA): Returns all of a user's messages and threads from the Inbox.
notes.get: Returns a list of all of the visible notes written by the specified user.
notifications.get: Returns information on outstanding Facebook notifications for current session user.
notifications.getList: Returns all the current session user's notifications.
pages.getInfo: Returns all visible pages to the filters specified.
pages.isAdmin: Checks whether the logged-in user is the admin for a given Page.
pages.isAppAdded: Checks whether the Page has added the application.
pages.isFan: Checks whether a user is a fan of a given Page.
status.get: Returns the user's current and most recent statuses.
stream.get: This method returns an object (in JSON-encoded or XML format) that contains the stream from the perspective of a specific viewer -- a user or a Facebook Page.
stream.getComments: This method returns all comments associated with a post in a user's stream. This method returns comments only if the user who owns the post (that is, the user published the post to his or her profile) has authorized your application.
stream.getFilters: This method returns any filters a user has specified for his or her home page stream.
users.getInfo: Returns a wide array of user-specific information for each user identifier passed, limited by the view of the current user.
users.getLoggedInUser: Gets the user ID (uid) associated with the current session.
users.getStandardInfo: Returns an array of user-specific information for use by the application itself.
users.hasAppPermission: Checks whether the user has opted in to an extended application permission.
users.isAppUser: Returns whether the user (either the session user or user specified by UID) has authorized the calling application.
users.isVerified (BETA): Returns whether the user is a verified Facebook user.
video.getUploadLimits (BETA): Returns the file size and length limits for a video that the current user can upload through your application.

Publishing Methods

Use these methods to edit and publish content to Facebook.

comments.add: Adds a comment for a given xid on behalf of a user. Calls with a session secret may only act on behalf of the session user.
comments.remove: Removes a comment for a given xid by comment_id. Calls with a session secret may only act on behalf of the session user.
links.post: Lets a user post a link on their Wall through your application.
links.preview: This method returns a preview of a shared link in the form of a stream attachment.
notes.create: Lets a user write a Facebook note through your application.
notes.delete: Lets a user delete a Facebook note that was written through your application.
notes.edit: Lets a user edit a Facebook note through your application.
status.set: Updates a user's Facebook status through your application. This is a streamlined version of users.setStatus.
stream.addComment: This method adds a comment to a post that was already published to a user's Wall.
stream.addLike: This method lets a user add a like to any post the user can see. A user can like each post only once.
stream.publish: This method publishes a post into the stream on the user's Wall and News Feed. This post also appears in the user's friends' streams (their News Feeds).
stream.remove: This method removes a post from a user's Wall. The post also gets removed from the user's and the user's friends' News Feeds. Your application may only remove posts that were created through it.
stream.removeComment: This method removes a comment from a post.
stream.removeLike: This method removes a like a user added to a post.
users.setStatus: Updates a user's Facebook status.
video.upload: Uploads a video owned by the current session user and returns the video.

Facebook Connect Methods

These methods are specific to Facebook Connect.

connect.getUnconnectedFriendsCount: Returns the number of friends of the current user who have accounts on your site, but have not yet connected their accounts. (for Facebook Connect).
connect.registerUsers: Creates an association between an existing user account on your site and that user's Facebook account, provided the user has not connected accounts before (for Facebook Connect).
connect.unregisterUsers: Unregisters a previously registered account (using connect.registerUsers). You should call this method if the user deletes his or her account on your site. (for Facebook Connect).

Mobile Methods

These methods are specific to mobile applications only.

sms.canSend: Determines whether a user has enabled SMS for the application.
sms.send: Sends a given text message (SMS) to the user.

Dashboard API Methods

These methods apply to the news, activity, and counters that comprise the Dashboard API.

Photos API Methods

photos.addTag: Adds a tag with the given information to a photo.
photos.createAlbum: Creates and returns a new album owned by the current session user.
photos.get: Returns all visible photos according to the filters specified.
photos.getAlbums: Returns metadata about all of the photo albums uploaded by the specified user.
photos.getTags: Returns the set of user tags on all photos specified.
photos.upload: Uploads a photo owned by the current session user and returns the new photo.

Events API Methods

These methods let you interact with Facebook Events.

events.cancel: Cancels an event. The application must be an admin of the event.
events.create: Creates an event on behalf of the user if the application has an active session; otherwise it creates an event on behalf of the application.
events.edit: Edits an existing event. The application must be an admin of the event.
events.get: Returns all visible events according to the filters specified.
events.getMembers: Returns membership list data associated with an event.
events.invite: Lets your application invite users to an event.
events.rsvp: Sets the attendance option for the current user.

Custom Tags API Methods

fbml.deleteCustomTags: Deletes one or more custom tags you previously registered for the calling application with fbml.registerCustomTags.
fbml.getCustomTags: Returns the custom tag definitions for tags that were previously defined using fbml.registerCustomTags.
fbml.registerCustomTags: Registers custom tags you can include in your that applications' FBML markup. Custom tags consist of FBML snippets that are rendered during parse time on the containing page that references the custom tag.

PHP Guru

Wednesday, March 3, 2010

Face Book API

API

Contents