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.
{ "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", }