Facebook API

A quick overview.

• Facebook developers [1] and API documentation [2]
• f8 keynote [3] Mark Zuckerberg talk.

• Facebook provides a REST [4] interface:
  • Send: GET/POST http://api.facebook.com/restserver.php?method=method.name&parameter1=value1&...
  • Get: XML (obeys facebook.xsd [5]) or JSON
• Write stand-alone applications, or web applications that user can to his facebook page.
• On web app. facebook will ping you every time.
• Once you authenticate (user logs in) you have access to some of his private information.

1. Get API key for your app, set the callback URL.

• Then, to get a user's private info (see authentication guide [6] for details):

1. Tell user to log into http://www.facebook.com/login.php?api_key=YOUR_API_KEY&v=1.0
2. He is then taken to the callback URL with an appeded token: http://mycalback.com/url?auth_token=abc123
3. Use this auth_token and send it to auth.createToken?api_key=YOUR_API_KEY&sig=MD5sig&v=1.0&auth_token=abc123 which will return a session_key and uid
4. Use this session_key in all future requests. Use uid when needed.

• api_key: for your app, which you got from the website.
• sig: MD5 hash of the current request and your secret key.
• v= 1.0
• format:: XML or JSON.
• callback: function name to prepend to response. Used for cross-domain requests with JSONP [7] and the script tag.

A few of the methods [8].

Admin.getAllocation [9]

Returns the current allocation limit for your application for the specified integration point.

Admin.getDailyMetrics [10]

Returns specified daily metrics for your application, given a date range.

admin.getAppProperties [11] (BETA)

Returns values of properties for your applications from the Facebook Developer application.

admin.setAppProperties [12] (BETA)

Sets values for properties for your applications in the Facebook Developer application.

application.getPublicInfo [13] (BETA)

Returns public information about a given application (not necessarily your own).

auth.createToken [14]

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.getSession [15]

Returns the session key bound to an auth_token, as returned by auth.createToken [16] or in the callback URL.

batch.run [17] (BETA)

Execute a list of individual API calls in a single batch.

data.getCookies [18] (BETA)

Returns all cookies for a given user and application.

data.setCookie [19] (BETA)

Sets a cookie for a given user and application.

events.get [20]

Returns all visible events according to the filters specified.

events.getMembers [21]

Returns membership list data associated with an event.

fbml.refreshImgSrc [22]

Fetches and re-caches the image stored at the given URL.

fbml.refreshRefUrl [23]

Fetches and re-caches the content stored at the given URL.

fbml.setRefHandle [24]

Associates a given "handle" with FBML markup so that the handle can be used within the fb:ref [25] FBML tag.

feed.publishStoryToUser [26]

Publishes a News Feed story to the user corresponding to the session_key parameter.

feed.publishActionOfUser [27]

Publishes a Mini-Feed story to the user corresponding to the session_key parameter, and publishes News Feed stories to the friends of that user.

feed.publishTemplatizedAction [28]

Publishes a Mini-Feed story to the user or Page corresponding to the session_key or page_actor_id parameter.

fql.query [29]

Evaluates an FQL (Facebook Query Language) query.

friends.areFriends [30]

Returns whether or not each pair of specified users is friends with each other.

friends.get [31]

Returns the identifiers for the current user's Facebook friends.

friends.getAppUsers [32]

Returns the identifiers for the current user's Facebook friends who are signed up for the specific calling application.

friends.getLists [33]

Returns the identifiers for the current user's Facebook friend lists.

groups.get [34]

Returns all visible groups according to the filters specified.

groups.getMembers [35]

Returns membership list data associated with a group.

marketplace.createListing [36]

Create or modify a listing in Marketplace.

marketplace.getCategories [37]

Returns all the Marketplace categories.

marketplace.getListings [38]

Return all Marketplace listings either by listing ID or by user.

marketplace.getSubCategories [39]

Returns the Marketplace subcategories for a particular category.

marketplace.removeListing [40]

Remove a listing from Marketplace.

marketplace.search [41]

Search Marketplace for listings filtering by category, subcategory and a query string.

notifications.get [42]

Returns information on outstanding Facebook notifications for current session user.

notifications.send [43]

Sends a notification to a set of users.

notifications.sendRequest [44]

This method is disabled.

notifications.sendEmail [45]

Sends an email to the specified users who have the application.

pages.getInfo [46]

Returns all visible pages to the filters specified.

pages.isAdmin [47]

Checks whether the logged-in user is the admin for a given Page.

pages.isAppAdded [48]

Checks whether the Page has added the application.

pages.isFan [49]

Checks whether a user is a fan of a given Page.

photos.addTag [50]

Adds a tag with the given information to a photo.

photos.createAlbum [51]

Creates and returns a new album owned by the current session user.

photos.get [52]

Returns all visible photos according to the filters specified.

photos.getAlbums [53]

Returns metadata about all of the photo albums uploaded by the specified user.

photos.getTags [54]

Returns the set of user tags on all photos specified.

photos.upload [55]

Uploads a photo owned by the current session user and returns the new photo.

profile.setFBML [56]

Sets the FBML for a user's profile, including the content for both the profile box and the profile actions.

profile.getFBML [57]

Gets the FBML that is currently set for a user's profile.

users.getInfo [58]

Returns a wide array of user-specific information for each user identifier passed, limited by the view of the current user.

users.getLoggedInUser [59]

Gets the user ID (uid) associated with the current session.

users.hasAppPermission [60]

Checks whether the user has opted in to an extended application permission.

users.isAppAdded [61]

Returns whether the logged-in user has added the calling application.

users.setStatus [62]

Updates a user's Facebook status.

• The Friends.get [63] returns the identifiers of the current user's Facebook friends.
• You call it like:

http://api.facebook.com/restserver.php?method=Frients.get&api_key=YOURKEY
&session_key=YOURSK&call_id=123&sig=MD5HASH&v=1.0
&format=XML

• which will return something like:

<?xml version="1.0" encoding="UTF-8"?>
<friends_get_response xmlns="http://api.facebook.com/1.0/" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:schemaLocation="http://api.facebook.com/1.0/ http://api.facebook.com/1.0/facebook.xsd" 
  list="true">  
  <uid>222333</uid>  
  <uid>1240079</uid> 
</friends_get_response>

• or, in JSON

[222333,1240079]

• The Photos.get [64] returns all visible photos according to the filters specified.
• You send:

http://api.facebook.com/restserver.php?method=Photos.get&api_key=YOURKEY
&session_key=YOURSK&call_id=123&sig=MD5HASH&v=1.0
&subj_id=USERID
&format=XML

• To find all photos tagged by user USERID. You can similarly find all photos in an album (aid) or in a list (pids).
• It returns

<?xml version="1.0" encoding="UTF-8"?> 
<photos_get_response xmlns="http://api.facebook.com/1.0/" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://api.facebook.com/1.0/ http://api.facebook.com/1.0/facebook.xsd" 
  list="true">  
  <photo>  
    <pid>34585991612804</pid>  
    <aid>34585963571485</aid>  
    <owner>1240077</owner>  
    <src>http://ip002.facebook.com/v11/135/18/8055/s1240077_30043524_2020.jpg</src>  
    <src_big>http://ip002.facebook.com/v11/135/18/8055/n1240077_30043524_2020.jpg</src>  
    <src_small>http://ip002.facebook.com/v11/135/18/8055/t1240077_30043524_2020.jpg</src>  
    <link>http://www.facebook.com/photo.php?pid=30043524&id=8055</link>  
    <caption>From The Deathmatch (Trailer) (1999)</caption>  
    <created>1132553361</created>  
  </photo>  
  <photo>  
    <pid>34585991612805</pid>  
    <aid>34585963571485</aid>  
    <owner>1240077</owner>  
    <src>http://ip002.facebook.com/v11/135/18/8055/s1240077_30043525_2184.jpg</src>  
    <src_big>http://ip002.facebook.com/v11/135/18/8055/n1240077_30043525_2184.jpg</src>  
    <src_small>http://ip002.facebook.com/v11/135/18/8055/t1240077_30043525_2184.jpg</src>  
    <link>http://www.facebook.com/photo.php?pid=30043525&id=8055</link>  
    <caption>Mexico City, back cover of the CYHS Student Underground 1999.</caption>  
    <created>1132553362</created>  
  </photo> 
</photos_get_response>

• An app can appear on many different pages [65].

• Application Directory [66]
• About Page [67]
• Left Nav [68]
• Facebook Canvas Pages [69]
  • Home
  • User Dashboard
• Profile [70]
  • Profile Box
  • Profile Action Links
• Privacy Settings [71]
• News Feed [72]
• Alerts [73]
• Message Attachments [74]
• Requests [75]
• Interacting with Users [76]

You set your callback (URL) for each of these on the facebook website. They all require you to send back different markup.

• The Facebook Markup Language [77] is and HTML subset + facebook additions.
• What you return for display within user's pages.
• Uses fb namespace to denote their tags:
  • fb:name [78] renders as the name of the user specified:

    <fb:name uid="$tagger" capitalize="true" /> tagged a photo of <fb:name subjectid="$tagger" uid="$tagee" />
    

  • fb:is-in-network [79] dsplays content inside the tag only if the user is in a given network.

    <fb:is-in-network network="16777229" uid="1230541">User 1230541, you are in the 
      <fb:networklink nid="16777229" /> network!</fb:is-in-network>
    

  • fb:editor [80] creates a form with two columns, just like the form on the edit-profile page. The children of fb:editor specify the rows of the form.

    <fb:editor action="?do-it" labelwidth="100"> 
      <fb:editor-text label="Title" name="title" value=""/>  
      <fb:editor-text label="Author" name="author" value=""/>  
      <fb:editor-custom label="Status"> 
        <select name="state">  
          <option value="0" selected>have read</option>  
          <option value="1">am reading</option>  
          <option value="2">want to read</option>  
        </select>  
      </fb:editor-custom>  
      <fb:editor-textarea label="Comment" name="comment"/>  
      <fb:editor-buttonset>  
      <fb:editor-button value="Add"/>  
      <fb:editor-button value="Recommend"/>  
      <fb:editor-cancel /> 
      </fb:editor-buttonset> 
    </fb:editor>
    

    

• The Faceebook query language [81] provides and alternate API.
• It's SQL-like: SELECT name, pic FROM user WHERE uid=211031 OR uid=4801660.
• The tables include:
  1. user
  2. friend
  3. group
  4. event
  5. photo
  6. album
  7. listing
  8. page

SELECT name, affiliations FROM user
WHERE uid IN (SELECT uid2 FROM friend WHERE uid1=211031)
      AND "Facebook" IN affiliations.name AND uid < 10

SELECT src, caption, 1+2*3/4, caption, 10*(20 + 1) FROM photo
WHERE pid IN (SELECT pid FROM photo_tag WHERE subject=211031) AND
      pid IN (SELECT pid FROM photo_tag WHERE subject=204686) AND
      caption

Results in

<?xml version="1.0" encoding="UTF-8"?>
<fql_query_response xmlns="http://api.facebook.com/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://api.facebook.com/1.0/ http://api.facebook.com/1.0/facebook.xsd" list="true">
  <user>
    <name>Mark Zuckerberg</name>
    <affiliations list="true">
      <affiliation>
        <nid>50431648</nid>
        <name>Facebook</name>
        <type>work</type>
        <status/>
        <year/>
      </affiliation>
      <affiliation>
        <nid>16777217</nid>
        <name>Harvard</name>
        <type>college</type>
        <status>Undergrad</status>
        <year/>
      </affiliation>
      <affiliation>
        <nid>67108894</nid>
        <name>San Francisco, CA</name>
        <type>region</type>
        <status/>
        <year/>
      </affiliation>
    </affiliations>
  </user>
  <user>
    <name>Chris Hughes</name>
    <affiliations list="true">
      <affiliation>
        <nid>50431648</nid>
        <name>Facebook</name>
        <type>work</type>
        <status/>
        <year/>
      </affiliation>
      <affiliation>
        <nid>16777217</nid>
        <name>Harvard</name>
        <type>college</type>
        <status>Alumnus/Alumna</status>
        <year>2006</year>
      </affiliation>
      <affiliation>
        <nid>67108869</nid>
        <name>Washington, DC</name>
        <type>region</type>
        <status/>
        <year/>
      </affiliation>
      <affiliation>
        <nid>67108894</nid>
        <name>San Francisco, CA</name>
        <type>region</type>
        <status/>
        <year/>
      </affiliation>
    </affiliations>
  </user>
  <user>
    <name>Dustin Moskovitz</name>
    <affiliations list="true">
      <affiliation>
        <nid>50431648</nid>
        <name>Facebook</name>
        <type>work</type>
        <status/>
        <year/>
      </affiliation>
      <affiliation>
        <nid>16777217</nid>
        <name>Harvard</name>
        <type>college</type>
        <status>Undergrad</status>
        <year/>
      </affiliation>
      <affiliation>
        <nid>16777219</nid>
        <name>Stanford</name>
        <type>college</type>
        <status>Staff</status>
        <year/>
      </affiliation>
      <affiliation>
        <nid>67108894</nid>
        <name>San Francisco, CA</name>
        <type>region</type>
        <status/>
        <year/>
      </affiliation>
      <affiliation>
        <nid>67108896</nid>
        <name>Silicon Valley, CA</name>
        <type>region</type>
        <status/>
        <year/>
      </affiliation>
      <affiliation>
        <nid>67109006</nid>
        <name>Ocala, FL</name>
        <type>region</type>
        <status/>
        <year/>
      </affiliation>
    </affiliations>
  </user>
</fql_query_response>


<?xml version="1.0" encoding="UTF-8"?>
<fql_query_response xmlns="http://api.facebook.com/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://api.facebook.com/1.0/ http://api.facebook.com/1.0/facebook.xsd" list="true">
  <photo>
    <src>http://photos-923.ak.facebook.com/ip002/v61/188/75/206412/s206412_31508923_7923.jpg</src>
    <caption>celebrating 23 years of ari's life at the one and the oasis.</caption>
    <anon>2.5</anon>
    <caption>celebrating 23 years of ari's life at the one and the oasis.</caption>
    <anon>210</anon>
  </photo>
  <photo>
    <src>http://photos-447.ak.facebook.com/ip005/v40/164/17/202965/s202965_30849447_4635.jpg</src>
    <caption>Liar's Dice...</caption>
    <anon>2.5</anon>
    <caption>Liar's Dice...</caption>
    <anon>210</anon>
  </photo>
  <photo>
    <src>http://photos-480.ak.facebook.com/ip005/v29/188/75/206412/s206412_30452480_140.jpg</src>
    <caption>the crew. (RishDAWG!)</caption>
    <anon>2.5</anon>
    <caption>the crew. (RishDAWG!)</caption>
    <anon>210</anon>
  </photo>
  <photo>
    <src>http://photos-103.ak.facebook.com/ip001/v12/188/75/206412/s206412_30325103_6676.jpg</src>
    <caption>group photo!!!!</caption>
    <anon>2.5</anon>
    <caption>group photo!!!!</caption>
    <anon>210</anon>
  </photo>
  <photo>
    <src>http://photos-399.ak.facebook.com/ip001/v10/188/75/206412/s206412_30191399_9134.jpg</src>
    <caption>someone is particularly happy to be in this picture</caption>
    <anon>2.5</anon>
    <caption>someone is particularly happy to be in this picture</caption>
    <anon>210</anon>
  </photo>
  <photo>
    <src>http://photos-716.ak.facebook.com/ip007/v16/129/99/204686/s204686_30190716_7256.jpg</src>
    <caption>One of the most extravagant.</caption>
    <anon>2.5</anon>
    <caption>One of the most extravagant.</caption>
    <anon>210</anon>
  </photo>
</fql_query_response>

• Similar idea to Google gadgets [82] and others.
• Two ideas:
  1. Open API to third parties. No brainer.
  2. Let others run apps on your website. Maybe
• Right now, startups love the traffic [83]. But, isn't it better to steal traffic away?
• Does OpenSocial [84] present a better [85] type of Internet platform [86]?
• Regardless, by 2013 linking to a web service will be as common as using a third-party library is now.