Socialwg/Social API/Facebook API

Overview

https://developers.facebook.com/docs/graph-api/reference/v2.2

Facebook API doesn't support all the functionality available from graphic interface. API documentation very often states: "You cannot publish/delete ??? using the Graph API."

Explorer

Facebook provides tool to explore its Graph API https://developers.facebook.com/tools/explorer

Nodes, Edges, Fields

https://developers.facebook.com/docs/graph-api/quickstart/v2.2

The Graph API is named after the idea of a 'social graph' - a representation of the information on Facebook composed of nodes, edges and fields. In some cases node can have field and edge with the same name eg. like which as field stores number of likes and as edge links to array of likes. At the same time an event has attending_count field and attending edge.

nodes

Basically "things" such as a User, a Photo, a Page, a Comment.

Each node has a unique id, in some cases an ID has another ID as its first half firstId_secondId (eg. comments)
Some nodes also have username, which one can use in place of id eg. elf.pavlik, polyeconomy

edges

The connections between those "things", such as a Page's Photos, or a Photo's Comments.

Sometimes some edges point to specializations of another edge. for example Group members & admins
In other cases it uses two steps edge, for example User events/declined where events itself doesn't point to a node with ID (see examples)

examples

Event: picture, attending, maybe, declined, noreply, invited, feed, photos, videos
Post: likes, comments, shareposts, insights, attachments
Group: members, admins,
User: ..., events, events/attending, events/maybe, events/not_replied, events/declined, events/created, ...

fields

Info about those "things", such as the birthday of a User, or the name of a Page

id: node's ID
link: node's Facebook URL

elf Pavlik: reminds me of discussions about @id and url in schema.org

By default API doesn't return all the fields available for requested node. To select only some of the available fields one can pass them as arguments. It also supports nesting via edges eg.

   ?fields=albums.limit(5){name, photos.limit(2){name, picture, tags.limit(2)}},posts.limit(5)

fields: name
edges: albums, photos, tags, posts

enumerations

move to Socialig/Vocabulary_TF

rsvp_status: attending, unsure, declined, not_replied
backdated_time_granularity(photo): year, month, day, hour, min, none
type (album): app, cover, profile, mobile, wall, normal, album
auth_referral_default_activity_privacy (app): SELF, EVERYONE, ALL_FRIENDS, NONE
auth_referral_response_type (app): code, token
list_type (friendlist): close_friends, acquaintances, restricted, user_created, education, work, current_city, family
order (object/comments): chronological, ranked
filter(object/comments): toplevel, stream
price_range(price_range): $ (0-10), $$ (10-30), $$$ (30-50), $$$$ (50+), Unspecified
status_type(post): mobile_status_update, created_note, added_photos, added_video, shared_story, created_group, created_event, wall_post, app_created_story, published_story, tagged_in_photo, approved_friend
type (post): link, status, photo, video

Collections and paging

https://developers.facebook.com/docs/graph-api/using-graph-api/v2.2#paging

HTTP verbs

GET - read
POST - create and update
DELETE - delete

To support clients that do not support all HTTP methods, you can alternatively issue a POST request to an endpoint with the additional argument method=delete to override the HTTP method.

Metadata

To get this information, add metadata=1 to the Graph API request. It includes connections, fields and type

 {
    "name": {node-name},
    "metadata": {
       "connections": {
          "feed": "http://graph.facebook.com/me/feed",
          "picture": "https://graph.facebook.com/me/picture",
          ....
       }
       "fields": [
         {
           "name": "id",
           "description": "The user's Facebook ID. No `access_token` required. `string`."
         },
         ....
       ],
       "type": "user"
    }
 }

In some cases it returns more information then documented on https://developers.facebook.com/docs/graph-api/reference/v2.2 !!! eg. /{event-id}/admins

Entities

Profile: A profile can be a User, a Page, a Group, an Event. The profile object is used within the Graph API to refer to the generic type that includes all of these other objects. The individual reference docs for each profile type should be used instead.
User: A user represents a person on Facebook.
Friend List: A friend list - an object which refers to a grouping of friends created by someone or generated automatically for someone (such as the "Close Friends" or "Acquaintances" lists).
Group: Represents a Facebook group.
Page: This represents a Facebook Page.
Event: Represents a Facebook event.
Post: An individual entry in a profile's feed. The profile could be a user, page, app, or group.
Milestone: This represents a milestone on a Facebook Page.
Status: A status message in a profile's feed.
Link: A link shared on a wall.
Photo: Represents an individual photo on Facebook.
Album: Represents a photo album.
Video: An individual video on Facebook.
Comment: A comment can be made on various types of content on Facebook. Most Graph API nodes have a /comments edge that lists all the comments on that object.
Message: An individual message in the Facebook messaging system.
Conversation: A Facebook Messages conversation between a person and a Facebook Page.
App: A Facebook app. Apps are created, maintained and deleted in the app dashboard.

Page Categories

Page can have one category and multiple subcategories. From one of those groupings:

Local Busines or Place
Company, Organization or Institution
Brand or Product
Artist, Band or Public Figure
Entertainment
Cause or Community

detailed categories on Socialig/Research/Facebook/Categories

Actions

actions (object[]): The action links attached to the post. Action links are any other links shown below the feed story beside Like and Comment.
name (string): The name or label of the action link.
link (string): The URL of the action link itself.

Like
Comment
Share

   {
     "id": "SOME_FB_ID", 
     "actions": [
       {
         "name": "Comment", 
         "link": "https://www.facebook.com/SOME_FB_ID/posts/ANOTHER_FB_ID"
       }, 
       {
         "name": "Like", 
         "link": "https://www.facebook.com/SOME_FB_ID/posts/ANOTHER_FB_ID"
       }
     ]
   }

NOTE: somehow actions seem not to provide proper URI to perform them, for example above actual endpoints:

like: POST graph.facebook.com/ANOTHER_FB_ID/likes
comment: POST graph.facebook.com/ANOTHER_FB_ID/comments

Search

https://developers.facebook.com/docs/graph-api/using-graph-api/v2.2#search

available search types: user, page, event, group, place, location, placetopic, ad_*

TODO: find out about Facebook Graph Search https://www.facebook.com/about/graphsearch

Errors

https://developers.facebook.com/docs/graph-api/using-graph-api/v2.2#errors

Examples

Common Scenarios

https://developers.facebook.com/docs/graph-api/common-scenarios

Are two people Facebook friends?

 /{user-a-id}/friends/{user-b-id} - this API Read modifier will let you check via API.

Does someone like a Facebook Page?

 /{user-id}/likes/{page-id} - this API Read modifier will let you check via API.

Publishing new Status Updates

 /{user-id}/feed for people on Facebook.
 /{page-id}/feed for Facebook Pages.

Uploading Photos and Creating Photo Albums

 /{user-id}/albums to create empty photo albums for people.
 /{user-id}/photos to add individual photos for people.
 /{page-id}/albums to create empty photo albums for Facebook Pages.
 /{page-id}/photos to add individual photos for Facebook Pages.
 /{album-id}/photos to add photos to an existing album for people or for Pages.

Sharing Links

 /{user-id}/feed for people on Facebook, using the link field.
 /{page-id}/feed for Facebook Pages, using the link field.

Responding to Events

 /{event-id}/attending to say the person is attending.
 /{event-id}/maybe to say the person might attend.
 /{event-id}/declined to say the person has declined to attend.

Example JSON

{
  "message": "Have you ever wondered what other songs used the same chord progression? This is kind of an amazing site that will tell you: http://www.hooktheory.com/trends",
  "created_time": "2015-09-30T04:59:59+0000",
  "updated_time": "2015-09-30T04:59:59+0000",
  "coordinates": {
  },
  "application": {
    "link": "http://aaronparecki.com/",
    "name": "aaronparecki.com",
    "id": "163993483698061"
  },
  "from": {
    "name": "Aaron Parecki",
    "id": "11500459"
  },
  "id": "11500459_10102200453435586",
}