This is my initial release of a slide deck used to support a quick training to students on Facebook and Twitter API. A lot of stuff would need to be fixed (my english first as a non-native writer :-). It also does not (yet?) cover all APIs. This support is better with associated resources such as the underlying Postman request collections. Please feel free to give feedback if any.

1. Application
Programming
Interface
Facebook
http://www.slideshare.net/fabricedelhoste
Twitter
fabrice@delhoste.com
Facebook: http://www.facebook.com/fabricedelhoste
Twitter: @spifd
Déc. 2013

2. Content
•
API
•
Social Networks
•
Facebook
•
Twitter
2

3. Warning
These slides are for training or educational purposes.
They do not replace reference documentation.
!
This is my first version, december 2013.
If you read this in 2013+, check for deprecation.
Feel free to give me your feedback.
!
Pictures and clip arts are free for use.
Credits coming on next release.
3

4. API
Application Programming Interface

5. API?
•
Application Programming Interface
•
Software-to-software contract
•
Defines the interactions between components
5

6. API
A good API can provide…
•
Flexibility
•
Security
•
Ease of use
•
Simplicity
Modern software are made of APIs
•
Scalability
•
Portability
Otherwise, it would serve a limited purpose
6

7. API
Design Patterns
•
Separating interface from implementation
!
•
Façade design pattern
•
A simplified interface to a larger body of code
•
Make software easier and convenient to use
•
Reduce dependencies
•
Wrap a poorly designed APIs with a single well-designed API
7

8. API
Platform
•
Developers can be:
•
•
•
customers
channels to customers
Offering them friendly helpful API is business-oriented
•
cost-reduction
•
time-to-market
•
know-how and expertise
8

9. API
Cloud Computing
•
Infrastructure-as-a-Service (IaaS) - infra level
•
•
Platform-as-a-Service (PaaS) - service level
•
•
API provides messaging system, databases, execution environment
Software-as-a-Service (SaaS) - application level
•
•
API provides control, distribution, network, and workload.
API mediates between apps and underlying IT infrastructure
Backend-as-a-Service (BaaS) - application dev level
•
API provides unified way to connect apps to cloud services
9

10. API
General Recommendations
•
Try test-driven design
•
Think about what client really needs, not what your server can offer !
•
Choose vocabulary wisely
•
Use standard when possible
•
Copy & enhance popular existing APIs
•
Be self-descriptive, developer-friendly
•
Try defining highest level of API
10

11. API
Practical Work
•
Real world use case analysis
•
What would you have done?
11

12. HTTP
Quick Overview

13. HTTP
•
Application protocol for distributed hypermedia systems.
•
Request / response
•
Stateless
•
Media independent
•
Foundation of the WWW
•
Current version: 1.1
13

14. HTTP
Request Format
•
Request line
•
Request headers
•
Empty line.
•
Optional message body.
POST /1.1/lists/create.json?name=My%20new%20list&mode=private HTTP/1.1
X-HostCommonName: api.twitter.com
Authorization: OAuth oauth_consumer_key= …
Host: api.twitter.com
Content-Length: 0
X-Target-URI: https://api.twitter.com
Content-Type:application/x-www-form-urlencoded; charset=UTF-8
Connection: Keep-Alive
!
!
!
!
14

15. HTTP
Response Format
•
Status line
•
Response headers
•
Empty line
•
Optional message body
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
last-modified: Sun, 08 Dec 2013 20:41:48 GMT
status: 200 OK
date: Sun, 08 Dec 2013 20:41:48 GMT
Connection: close
content-length: 1879
!
{
"id_str": "101144843",
"full_name": "@spifd/lists/my-new-list",
"user": {
"id_str": "18229030",
…
15

16. HTTP
URL - Unified Resource Locator
Not sent to server.
Only browser.
HTTP: clear
HTTPS: encrypted
URL (or Percent) encoding
! # $ & ‘ ( ) * + , / : ; = ? @ [ ]
converted to
%21 %23 %24 …
16

17. HTTP
Verbs (methods)
•
GET: retrieve a resource
Others
•
•
•
HEAD: GET without body
•
•
safe: it must not modify resources
idempotent: 1 call, same as multiple calls
•
TRACE: echo request back to the sender
•
OPTIONS: supported HTTP verbs
•
CONNECT: connects to proxy
•
PATCH: partial update
PUT: create/update a resource
•
•
idempotent
POST: add a subordinate resource
!
•
not safe, not idempotent
Safe/idempotent:
•
•
DELETE: delete a resource
•
•
Only semantic, no constraint in protocol
idempotent
17

18. HTTP
Headers
•
General header: for both request and response messages.
•
•
Request header: only for request messages.
•
•
Ex: Authorization, Accept, Cookie, Host, User-Agent
Response header: only for response messages.
•
•
Ex: Cache-Control, Connection
Ex: Server, Set-Cookie
Entity header: metadata about the entity body
•
Ex: Content-Encoding, Content-Length, Content-Type, Last-Modified
18

19. HTTP
Request Parameters
•
For GET, part of the URL query string as field / value pairs
•
•
field1=value1&field2=value2&field3=value3…
For POST, request parameters are sent using:
•
Using "Content-type: application/x-www-form-urlencoded" (header)
•
•
The content body contains "field1=value1&field2=value2&field3=value3…"
Using "Content-type: "multipart/form-data" (header) for binary data
•
Special format using several parts separated with a particular string
boundary (content-disposition header), each part having its own contenttype header.
19

20. HTTP
Status Codes
•
1xx: Informational
•
2xx: Successful
4xx: Client Error
•
400: Bad Request
•
401: Unauthorized
3xx: Redirection
•
403: Forbidden
302: Found
•
404: Not Found
304: Not modified (f-Modified-Since header)
•
405: Method Not Allowed
•
•
•
•
•
!
!
!
201: Created (PUT & POST)
•
5xx: Server Error
•
500: Internal Server Error
•
503: Service Unavailable
20

21. HTTP
Security
•
Authorization Header
•
Allows different kind of authentication : basic, digest, oauth
•
Authorization: {Type} {Data}
•
Ex: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
•
•
RFC2045-MIME variant of Base64 encoding of “login:password”
Encryption with HTTPS = HTTP over SSL/TLS
•
Assymetric key derived into a short-term session key
•
Used to encrypt the whole HTTP data flow
21

22. HTTP
Disclaimer
HTTP Requests are NOT purely written to ease readability.
!
In particular:
- they do NOT strictly respect HTTP format
- they do NOT follow correctly URL-encoding when needed
- they do NOT contain all HTTP headers and body
!
We are humans, not machines.
22

23. Postman
Chrome App - Handy HTTP Client

24. Postman
24

25. API
Practical Work
•
Download and install Google Chrome
•
Download and install Postman (Packaged app)
•
•
•
http://www.getpostman.com/
If you want to inspect requests in Google Chrome network console, browse
chrome://flags and "Enable debugging for packed apps"
Take time to play and be familiar with Postman features
•
We’ll use it all along the training.
•
See how to create collections, to save them, …
•
I’ll collect your backup.
25

26. REST
Designing Lightweight APIs

27. REST
•
REpresentational State Transfer
•
Defined by HTTP 1.0 & 1.1 author (Roy Fielding)
•
Architectural style
•
REST = Transfer of representations of resources
!
•
A simple way to handle interactions between systems
27

28. REST
Main Principles
•
Identify everything with an identifier
•
Link things together
•
Use standards
•
Resources with multiple representations
•
Stateless
28

29. REST
Characteristics
•
Lightweight
•
Scalable
•
Simple
•
Flexible
•
Readable
•
Reliable
•
Efficient
•
Portable
!
!
29

30. REST
HTTP-based
•
Easy SOA (Service-Oriented Architecture)
•
•
SOAP is another way… often cumbersome
Pragmatic approach, mostly based on HTTP protocol
•
Well known, widely deployed, and avoid new layers
•
Use HTTP verbs
•
Use URI as a global identifier for resources
30

31. REST
RESTful Constraints
•
Client-server: separation of concerns, separate interface from implementation
•
Stateless server: requests contains all necessary information
•
Cache: responses can be cached or not
•
Uniform interface:
•
Identification of resources: each resource is uniquely identified
•
Manipulation of resources through representations: each resource has one or more representations
•
Self-descriptive message: message is not only data but everything necessary for the message to be processed
•
Hypermedia as the engine for application state (HATEOAS): the server must give the client the needed
information to navigate the service
•
Layered system: client has no idea about the end server or intermediates processing the requests
•
Code-on-demand (optional): client are extendable by downloading code
31

32. REST
CRUD
•
POST = CREATE
•
GET = READ
•
PUT = UPDATE
•
DELETE = DELETE
•
Alternative: POST /dogs?method=delete
•
Filtering proxies, …
32

33. REST
Resources
•
Use nouns, no verb
•
Plural: /dogs
•
Concrete: /dogs instead of /animals
•
Use Javascript naming convention
33

34. REST
Collections
•
2 base URLs per resource
•
Collection
•
•
/dogs
Element
•
/dogs/1234
34

35. REST
Requests for resources
•
GET /owners/5678/dogs
•
POST /owners/5678/dogs
•
GET /dogs?color=red&state=running&location=park
•
GET /dogs?fields=name,color,location.city
•
GET /dogs.xml?limit=25&offset=50
•
GET /owners/5678/dogs?q=Bobby (search)
35

36. REST
Requests for non-resources
•
Use verbs for non-resources: compute, search, …
•
GET /convert?from=EUR&t=CNY&amount=100
•
GET /search?q=toto (global search)
•
GET /owners/5678/dogs/search?q=toto
•
GET /dogs/count
36

37. REST
Handling errors
•
Use HTTP status codes. Those are enough for most usages:
•
•
304: Not modified
•
400: Bad Request, 401: Unauthorized, 403: Forbidden, 404: Not Found
•
•
200: OK, 201: Created
500: Internal Server Error
Be verbose and self-descriptive in response body. Example:
{"developerMessage" : "Verbose, plain language description of the problem for the app
developer with hints about how to fix it.", "userMessage":"Pass this message on to
the app user if needed.", "errorCode" : 12345, "more info": "http://
dev.teachdogrest.com/errors/12345"}
37

38. REST
Versioning
•
Make version mandatory.
•
Use ‘v’ prefix to avoid confusion
•
Use one number. API is not implementation.
•
Ex: /v1/dogs
•
Recommendations:
•
Ascending compatibility with 1 version
•
Communicate very soon on (breaking) changes.
38

39. REST
REST API Design State of the art
!
•
You want to become a REST ninja?
•
Read everything from:
•
https://apigee.com/about/api-best-practices
39

40. JSON
Overview

41. JSON
•
http://www.json.org/
•
JavaScript Object Notation
•
Lightweight standard for data-interchange format
•
Developer-friendly
•
•
•
Easy for humans to read/write
Efficient to parse/generate
Open, not only Javascript
41

42. JSON
Types
Number
Array: ordered values
12
[ 1, "apple", true, { … } ]
2.45 324.0594
String
"hello"
Object: unordered key/value pairs.
’hello’
{ "title": "Games of Thrones", "season": 1 }
Boolean
true
false
Empty value
null
42

43. JSON
Example
{
"id": "4",
"favorite_teams": [
{
"id": "116174408393207",
"name": "Yankees"
}
],
"name": "Mark Zuckerberg",
"hometown": {
"id": "105506396148790",
"name": "Dobbs Ferry, New York"
}
}
43

44. API
Practical Work
•
In Postman, create a "API Todo" HTTP request collection
•
Think about a REST API for todo list
•
•
Create/read/update/delete a todo
•
•
Create/read/update/delete a todo list
Read part of the data of a todo
Imagine being a client and write all HTTP requests
•
No server development, just URL and payload in Postman
44

45. oAuth
Overview

46. oAuth ?
•
http://oauth.net/
•
An open authentication protocol to allow secure
authorization in a simple and standard method from web,
mobile and desktop applications.
•
•
•
Get away from login and passwords to grant authorizations to 3rd parties
Publish and interact safely with users data
oAuth now widely used
•
Facebook, Google, Twitter, …
46

47. oAuth
Before
•
Applications stored passwords
•
Full access to user’s account
•
Revoke application permissions by changing password
•
Bad guys could get the user’s password
•
Many proprietary solutions
47

48. oAuth
Principle
•
An external Guest A says to the reception desk that he wants to meet
Employee B for business purposes.
•
The reception desk notifies Employee B that Guest A has come to visit
him.
•
Employee B comes to the reception desk and identifies Guest A.
•
Employee B records the business purpose and identity of Guest A at the
reception desk.
•
The reception desk issues a visitor card to Guest A.
•
Employee B and Guest A go to the specified room to discuss their
business.
48

49. oAuth 1.0

50. oAuth 1.0
50

51. oAuth 1.0
•
Getting a request token and define callback URL
•
Direct the user to authorization flow (login dialog)
•
Callback to your URL with request token
•
Exchange request token for an access token
•
Send requests signed with access token
51

52. oAuth 2.0

53. oAuth 2.0
•
Simplified signature
•
No encryption, replaced by HTTPS
•
Easier to handle.
•
Token Expiration
•
Scope: limit access to 3rd party
•
Left to oAuth providers, proprietary values
53

54. oAuth 2.0
Apps
•
Web-server apps (grant_type=authorization_code)
•
•
Username/password access (grant_type=password)
•
•
Get an access token from login/password. No server-side code needed. Only for
trusted clients.
Application access (grant_type=client_credentials)
•
•
Server exchanges a code for an access token.
Get an accès token from client secret.
Browser and Mobile apps (grant_type=implicit)
•
Browser or mobile app receives directly an access token. No server-side code needed.
54

55. oAuth 2.0
Example: Web-server Apps
55

56. oAuth 2.0
Example: Web-server Apps
•
Getting a request token and define callback URL
•
Direct the user to authorization flow (login dialog)
•
Callback to your server with code
•
Exchange code for an access token
•
Send (not sign) requests with access token as HTTP query
parameter or Authorization header
•
Renew access token when expired
(grant_type=refresh_token)
56

57. Social Networks
Overview

58. Social Media

59. Social Network
•
A platform to handle social interactions between actors
•
People, Community, and Companies
•
Sharing Interests and Activities
•
Communications
59

60. Social Networks
•
Worldwide.
•
Facebook
•
Twitter IPO
60

61. Social Networks
Are they all the same?
61

62. Facebook

63. Facebook
Overview

64. Facebook
The Social Network
•
Founded in 2004
•
CEO: Mark Zuckerberg
•
1.19 billion monthly active users.
•
728 million daily active users.
•
874 million mobile users.
64

65. Facebook?
•
Re-index the web around personal information.
•
Identity provider across the web and mobile apps
•
Replace communications channels
•
Behavioural ad network
•
Personalized search engine
•
Customized and socialized experiences everywhere
65

66. Facebook
Features
•
Status updates
•
Phone
•
Photo / Video
•
App Center Promotions
•
Timeline
•
Ads
•
Messages
•
Payment
•
Chat
•
Pages
•
SMS
•
Groups
•
Checkin
•
…
66

67. Facebook
Features
Graph Search
Post Status / Photo / Video / Place / …
Go to Settings
Go to
Timeline
Main Menu
Groups, Apps,
Friend lists,
Pages
Ticker
Ads
&
Suggestions
Chat
Newsfeed
67

68. Facebook
Concerns
•
Privacy
•
Loss of control
•
•
Service and Content Provider
Competitors
•
Google
•
Twitter
•
Yahoo
•
Whatsapp, WeChat, Snapchat, Pinterest, …
68

69. Facebook
References
•
www.facebook.com
•
developers.facebook.com
69

70. Facebook Platform
Practical Work
•
Create your Facebook account
•
Activate your developer account
•
Try to create an application
•
Prepare your phone to receive SMS confirmation if your Facebook
account is not yet a "verified" account.
•
https://developers.facebook.com
70

71. Facebook
Platform

72. Facebook Platform
•
A social operating system
•
•
Access data in Facebook
•
•
Develop and test applications on top of Facebook APIs
Monitor application usage
For:
•
Applications on Facebook
•
External websites
•
Device and Mobile apps
72

73. Facebook Platform
APIs
•
Graph API
•
Iframes
•
FQL
•
Log in with Facebook
•
Real-time Updates
•
Open Graph Protocol
•
Authentication
•
Social Plugins
73

74. Facebook Platform
Terms & Conditions
•
It’s free!
•
You cannot cache Facebook’s data as you want
•
You cannot re-create social graph
•
You cannot use Facebook’s data for ads
•
Facebook has the right to blacklist your application
•
…it’s free!
74

75. Facebook Platform
API Limitations
•
Can’t invite friends
•
Can’t confirm, ignore, or delete friendship
•
Can’t post to another user’s timeline
•
Can’t get friends’ phones or e-mails
•
Can’t send private message to people
•
Can’t be notified on all kind of events
•
Can’t read the full graph : no friends of friends
•
Can’t get social graph ranking (interactions)
•
Can’t search through Graph Search API
•
…
•
API Rate Limits: https://developers.facebook.com/docs/reference/ads-api/api-rate-limiting/#userlimit
75

76. Facebook Platform
Creating and Configuring an Application

77. Facebook Platform
Creating an application
Basic Settings
Your Application Identifier a.k.a. API Key
Your Application Secret a.k.a. Client Secret
!
Very important: needed for authentication
77

78. Facebook Platform
Configuring an application
Basic Settings
Verified when adding your app.
78

79. Facebook Platform
Configuring an application
Roles
Administrators: complete access
!
Developers: can modify settings but cannot reset
secret key, manage users, or delete app
!
Testers: can test the application in sandbox mode
but cannot modify the application
!
Insight Users: can access analytics but cannot
modify the application
79

80. Facebook Platform
Configuring an application
Advanced Settings
Monitor and track changes of your app settings.
Security settings are very important to avoid hackers to
spoof your FB app.
80

81. Facebook Platform
Configuring an application
Status & Review
When not live, the app is said to be in "Sandbox mode":
only administrators, developers, and testers can install and
use your app.
81

82. Facebook Platform
Practical Work
•
Log on you Facebook account
•
Create your own application
•
Create a test user
•
Log with the test user and back to your account
•
Create and use Chrome profiles to switch between
accounts
82

83. Facebook
Authentication & Authorization

84. Facebook Authentication & Authorization
Login with Facebook
•
When you click this button, it give permissions to a FB application:
•
•
If not, prompt them to do so through a Login dialog
•
Secure codes are exchanged to confirm identity
•
•
It first checks whether someone is already logged in
If confirmed, an access token is retrieved
The app’s developer will then use the access token to interact with
Facebook on behalf of the user.
84

85. Facebook Authentication & Authorization
Security Model
•
Based on oAuth 2.0
•
•
Access token and HTTPS
Permissions
•
Protect every piece of Facebook data
•
Under user’s review and control during application approval
85

86. Facebook Authentication & Authorization
Access Tokens
•
User Access Token
•
•
•
To read/write on behalf of a FB user
Interactive login dialog
App Access Token
•
•
•
To read/write on behalf of a FB application
Server-to-server call
Page Access Token
•
•
•
To read/write on behalf of a FB page
Obtained through Graph API with a valid user access token
Client Token
•
Native mobile or desktop apps to access limited data on behalf of a FB application.
•
Rarely used.
86

87. Facebook Authentication & Authorization
User Access Token
•
Unique
•
Associated to a scope (permissions)
•
•
Define the usage bounds
Short-lived ~1 hour, or Long-lived ~60 days
•
•
Short-lived mainly used for web applications
•
•
Long-lived obtained from short-lived
Long-lived mainly used for native mobile apps and server-side
Automatic with SDK for Javascript, iOS, and Android.
87

88. Facebook Authentication & Authorization
Permissions

89. Facebook Authentication & Authorization
Permissions
User Permissions
•
user_about_me
•
user_friends
•
user_photos
•
user_actions.books
•
user_games_activity
•
user_questions
•
user_actions.music
•
user_groups
•
user_relationship_details
•
user_actions.news
•
user_hometown
•
user_relationships
•
user_actions.video
•
user_interests
•
user_religion_politics
•
user_activities
•
user_likes
•
user_status
•
user_birthday
•
user_location
•
user_subscriptions
•
user_checkins
•
user_notes
•
user_videos
•
user_education_history
•
user_online_presence
•
user_website
•
user_events
•
user_photo_video_tags
•
user_work_history
89

90. Facebook Authentication & Authorization
Permissions
Friends Permissions
•
friends_about_me
•
friends_games_activity
•
friends_questions
•
friends_actions.books
•
friends_groups
•
•
friends_actions.music
•
friends_hometown
friends_relationship_detail
s
•
friends_relationships
•
friends_religion_politics
•
friends_status
•
friends_subscriptions
•
friends_videos
•
friends_website
•
•
•
•
•
friends_actions.news
friends_actions.video
friends_activities
friends_birthday
friends_checkins
•
•
•
•
•
friends_interests
friends_likes
friends_location
friends_notes
friends_online_presence
•
friends_education_history
•
friends_photo_video_tags
•
friends_events
•
friends_photos
90

91. Facebook Authentication & Authorization
Permissions
Extended Permissions
•
ads_management
•
photo_upload
•
read_stream
•
ads_read
•
publish_actions
•
rsvp_event
•
create_event
•
publish_checkins
•
share_item
•
create_note
•
publish_stream
•
sms
•
email
•
read_friendlists
•
status_update
•
export_stream
•
read_insights
•
video_upload
•
manage_friendlists
•
read_mailbox
•
xmpp_login
•
manage_notifications
•
read_page_mailboxes
•
manage_pages
•
read_requests
91

92. Facebook Authentication & Authorization
Sending Requests

93. Facebook Authentication & Authorization
Sending Requests
Example
Using HTTPS (TLS) protects the request
information.
GET https://graph.facebook.com/me?access_token=CAAKzZBdx5dcABAIA9Q…
Access token is a secret value to include as a
query parameter attached to the HTTP request
93

94. Facebook Authentication & Authorization
Sending Requests from Server with Enhanced Security
App Secret Proof
•
Hackers can steal access token client-side or server-side
•
•
•
Client malware
Server attacks
Using App Secret Proof makes this harder server-side
•
Activate in application dashboard under advanced settings:
!
•
Access token integrity and authentication is now verified by Facebook.
94

95. Facebook Authentication & Authorization
Sending Requests from Server with Enhanced Security
Computing App Secret Proof
•
Add query parameter to all of your server-side requests
•
appsecret_proof = HMAC-SHA256(key, message)
•
HMAC-SHA256 = Hash Message Authentication Code
•
key = {app_secret}
•
message = {access_token}
95

96. Facebook Authentication & Authorization
Sending Requests from Server with Enhanced Security
Example
https://graph.facebook.com/me?access_token=CAAKzZBdx5dcABAIAjZBs9Q…
&appsecret_proof=…
Compute and add this query
parameter to every request.
96

97. Facebook Authentication & Authorization
Client-side User Authentication

98. Facebook Authentication & Authorization
Step 1 - Login Dialog (Browser)
GET (In Browser) https://www.facebook.com/dialog/oauth?
client_id=760835680597440
&redirect_uri=http%3A%2F%2Ffabrice.delhoste.com%2F
&response_type=token
&scope=read_stream,user_friends,status_update
Read
Publish
Application Id
Set to the value defined in app
dashboard
Request for access token
(client-side)
This is a short-lived access token
(~2 hours).
URL fragment id # are NOT sent
to server.
Set to
"Only me"
in paranoïa
mode
http://fabrice.delhoste.com#access_token=CAAKzZBdx5dcABABBHv8vXR1…
&expires_in=6258
98

99. Facebook Authentication & Authorization
Step 2 - Convert short-lived to long-lived access token (optional)
GET https://graph.facebook.com/oauth/access_token?
client_secret=9e4461c0364f179e6c9f12adf16b7cc9
&client_id=760835680597440
&grant_type=fb_exchange_token
&fb_exchange_token=CAAKzZBdx5dcABABBHv8vXR1…
Application
Secret
This is short-lived access token obtained
previously obtained.
This is long-lived access token (~60 days).
access_token=CAAKzZBdx5dcABAM8oQG1ivoyBZBC9…
&expires=5181099
99

100. Facebook Authentication & Authorization
Review User’s application Settings (1)
You can find more here…
100

101. Facebook Authentication & Authorization
Review User’s application Settings (2)
Use "Only me"
when in doubt
Permissions
Detect unusual activity or
simply purge unused apps.
101

102. Facebook Authentication & Authorization
Server-side User Authentication

103. Facebook Authentication & Authorization
Step 1 - Login Dialog (Browser)
GET (In Browser) https://www.facebook.com/dialog/oauth?
client_id=760835680597440
&redirect_uri=http%3A%2F%2Ffabrice.delhoste.com%2F
&response_type=code
&scope=read_stream,user_friends,status_update
Read
Publish
Application Id
Set to the value defined in app
dashboard
Request for code
(server-side)
Can be used once and
expires shortly.
Set to
"Only me"
in paranoïa
mode
http://fabrice.delhoste.com/?
code=AQCtOF4xjIObCApYPFsTwMy2AumKjEi2fw97az7UMBVrhSH-r59SLS…
103

104. Facebook Authentication & Authorization
Step 2 - Exchange code for long-lived access token
GET https://graph.facebook.com/oauth/access_token?
Application
client_id=760835680597440
Secret
&redirect_uri=http%3A%2F%2Ffabrice.delhoste.com%2F
&client_secret=9e4461c0364f179e6c9f12adf16b7cc9
&code=AQCtOF4xjIObCApYPFsTwMy2AumKjEi2fw97az7UMBVrhSH-r59SLS…
client_secret is the Application Secret.
Server-side only (security).
Never, ever, put app-secret in client !code.
Because we use "code" confirmation supposed to be used for server-side, this is longlived access token associated to the user, the application, and the requested permissions.
(~60 days)
access_token=CAAKzZBdx5dcABALYm0KZBcPSm2oVepJ8MZ…
&expires=5181609
104

105. Facebook Authentication & Authorization
Server-side Application Authentication

106. Facebook Authentication & Authorization
Step 1 - Login Dialog (Browser)
GET (in Browser)
https://graph.facebook.com/oauth/access_token?
client_id=760835680597440
&client_secret=7bdde89123d51317e6bd7e644d5202fd
&grant_type=client_credentials
Application Id
Application
Secret
access_token=760835680597440|MeOsSs6rIfH0SolW53nJnG8Atzs
106

107. Facebook Authentication & Authorization
Debugging Tokens

108. Facebook Authentication & Authorization
Debugging Tokens Tool
108

109. Facebook Authentication & Authorization
Debugging Tokens API
GET https://graph.facebook.com/debug_token?
input_token=CAAKzZBdx5d…
&access_token=CAAKzZBdx5dcAB…
The token to debug.
{
"data": {
"error": {
"message": "Error validating access token: Session does not match current…",
"code": 190,
"subcode": 460
},
"app_id": 760835680597440,
"is_valid": false,
"application": "Training API",
"user_id": 702008335,
"expires_at": 0,
"scopes": [
"read_stream",
"status_update",
"user_friends",
…
]
}
}
109

110. Facebook Authentication & Authorization
Graph API Explorer
Authenticate and Explore Facebook API easily

111. Facebook Authentication & Authorization
Graph API Explorer
Features

112. Facebook Authentication & Authorization
Graph API Explorer
Permissions

113. Facebook Authentication & Authorization
Open Graph Debugger

114. Facebook Authentication & Authorization
Access Token Tool

115. Facebook Authentication & Authorization
Practical Work
•
In Postman and your browser, build a "FB Auth"
collection of HTTP requests to:
•
Get long-lived client-side access token with permissions to get all
birthdays
•
Get server-side access token with permissions to read the
newsfeed, publish status and photos
•
Debug those tokens
115

116. Facebook
Graph API

117. Facebook
Graph API ?
•
Doc: https://developers.facebook.com/docs/graph-api/reference
•
Endpoint: https://graph.facebook.com/
•
Get data in and out of Facebook’s social graph.
•
Read
•
Publish
•
Update
•
Delete
•
Search
117

118. Facebook
Graph API
Overview
•
Object-oriented
•
•
•
Every object has a unique identifier
Connections
All data returned as JSON objects
Objects
Objects : https://graph.facebook.com/{ID}
•
https://graph.facebook.com/25465437753
•
•
Object
https://graph.facebook.com/fabricedelhoste
Connections : https://graph.facebook.com/me/{connection}
•
https://graph.facebook.com/25465437753/friends
•
https://graph.facebook.com/me/friends
118

119. Facebook
Graph API
Root Objects
Achievement
Event
Offer
Question
Album
FriendList
Order
QuestionOption
Application
Group
Page
Review
Checkin
Insights
Payment
Comment
Link
Photo
Status
message
Domain
Errors
Message
Note
Pictures
Post
Thread
User
Video
119

120. Facebook Graph API
Reading
•
GET HTTP request
•
Different permissions applied to objects/fields/connections
•
•
Access token required for most of personal data
Response:
{
!
"fieldname": {field-value},
…
!
}
!
•
Special object: /me : it’s me in the social graph !
120

121. Facebook
Graph API
Reading a public object
GET https://graph.facebook.com/markzuckerberg
{
"id": "4",
"name": "Mark Zuckerberg",
"first_name": "Mark",
"last_name": "Zuckerberg",
"link": "https://www.facebook.com/zuck",
"username": "zuck",
"hometown": {
"id": "105506396148790",
"name": "Dobbs Ferry, New York"
},
"location": {
"id": "104022926303756",
"name": "Palo Alto, California"
},
"bio": "I'm trying to make the world a more open place.",
"quotes": ""Fortune favors the bold."rn- Virgil, Aeneid X.284rnrn"All children are artists. The
problem is how to remain an artist once you grow up." rn- Pablo Picassornrn"Make things as simple as
possible but no simpler."rn- Albert Einstein",
"work": [
{
"employer": {
"id": "20531316728",
"name": "Facebook"
},
Vanity name
or
UID (User Id)
No access token needed
for public objects
By default, every
field are returned.
121

122. Facebook
Graph API
Introspection
GET graph.facebook.com/markzuckerberg?metadata=1
{
"id": "4",
"name": "Mark Zuckerberg",
"first_name": "Mark",
…
"metadata": {
"connections": {
"home": "https://.../home?access_token=CAAKz…",
"feed": "https://.../feed?access_token=CAAKz…",
"friends": "https://.../friends?access_token=CAAKz…",
"mutualfriends": "https://.../mutualfriends?access_token=CAAKz…",
"family": "https://.../markzuckerberg/family?access_token=CAAKz…",
…
"fields": [
{
"name": "id",
"description": "The user's Facebook ID…"
},
{
"name": "name",
"description": "The user's full name…
},
…
…
122

123. Facebook
Graph API
Selecting fields/connections
GET https://graph.facebook.com/me/friends?access_token=…
&fields=name,birthday
{
}
"data": [
{
"name": "Eric Therene",
"birthday": "12/22/1968",
"id": "1027414115"
},
{
"name": "Jeremy Marois",
"birthday": "01/23/1990",
"id": "1329818667"
},
…
]
Can filter fields AND
connections
123

124. Facebook
Graph API
Global Limit
GET https://graph.facebook.com/me/albums?access_token=…
&limit=5
{
"id": "702008335",
"albums": {
"data": [
{
"id": "10151819411378336",
"from": {
"name": "Fabrice Delhoste",
"id": "702008335"
},
"name": "Instagram",
"link": "https://www…",
"cover_photo": "10151819411413336",
"privacy": "everyone",
"count": 10,
My last 5 photo albums
…
124

125. Facebook
Graph API
Field Limit
GET https://graph.facebook.com/me?access_token=…
&fields=albums.limit(5)
{
"id": "702008335",
"albums": {
"data": [
{
"id": "10151819411378336",
"from": {
"name": "Fabrice Delhoste",
"id": "702008335"
},
"name": "Instagram",
"link": "https://www…",
"cover_photo": "10151819411413336",
"privacy": "everyone",
"count": 10,
My last 5 photo albums
Same as previous.
…
125

126. Facebook
Graph API
Mixing fields and limits
GET https://graph.facebook.com/me?access_token=…
&fields=albums.limit(5).fields(
name, photos.limit(1).fields(
name, picture
)
)
{
"id": "702008335",
Name and picture of each
"albums": {
first photo of my last 5
"data": [
photo albums.
{
"name": "Instagram",
"id": "10151819411378336",
"created_time": "2013-07-25T08:49:09+0000",
"photos": {
"data": [
{
"name": "Mod…",
"picture": "https://fbcdn…”,
…
126

127. Facebook
Graph API
Cursor-based Pagination
•
Cursor-based
•
•
•
Cursor marks an invariant point in a list of data
Preferred pagination (consistent even if objects have been created
or deleted in the meantime you got the page)
Not currently supported among all object types
•
•
Supported: photos, albums, links, notes, admins, comments, likes,
…
2 request parameters: before, after
127

128. Facebook
Graph API
Cursor-based Pagination
GET https://graph.facebook.com/283864466145_10151727303376146/likes
{
"data": [
Get likes of this page post id.
{
"id": "1018544972",
"name": "Tyrion Lannister"
},
{
"id": "100000974199494",
Before (or after) is always included.
"name": "Cersei Lannister"
},
Useful to poll for updates.
…
"paging": {
"cursors": {
"after": "MTMwMjc5OTMxOQ==",
Include link to paginate.
"before": "MTAxODU0NDk3Mg=="
},
"next": "https://graph.facebook.com/283864466145_10151727303376146/likes?
limit=25&after=MTMwMjc5OTMxOQ%3D%3D"
}
}
128

129. Facebook
Graph API
Cursor-based Pagination
GET https://graph.facebook.com/283864466145_10151727303376146/likes?
limit=25
&after=MTMwMjc5OTMxOQ%3D%3D
{
!
"data": [
{
"id": "1018544972",
"name": "Tyrion Lannister"
},
…
Moving forward
"paging": {
"cursors": {
"after": "MTU4NDc4MjE4MQ==",
"before": "MTM5NjgxODI0OA=="
},
"previous": "https://graph.facebook.com/283864466145_10151727303376146/likes?
limit=25&before=MTM5NjgxODI0OA%3D%3D",
"next": "https://graph.facebook.com/283864466145_10151727303376146/likes?
limit=25&after=MTU4NDc4MjE4MQ%3D%3D"
}
}
129

130. Facebook
Graph API
Offset-based Pagination
•
Offset-based
•
•
Supported by all objects
•
Can be combined with other type of pagination
•
•
Marks an offset point and a number of objects in a list of data
Used when chronology is useless
2 request parameters: limit, offset
130

131. Facebook
Graph API
Offset-based Pagination
https://graph.facebook.com/me/friends?access_token=…
&limit=10
&offset=10
Get friend number at current
indexes [10-20]
{
"data": [
{
"name": "Luke Skywalker",
"id": "100004245228110"
}
…
],
"paging": {
"next": "https://graph.facebook.com/702008335/friends?
limit=10&offset=20&access_token=CAAKzZB...&__after_id=739453773",
"previous": "https://graph.facebook.com/702008335/friends?
limit=10&offset=0&access_token=CAAKzZB...&__before_id=695205969"
}
}
131

132. Facebook
Graph API
Time-based Pagination
•
Time-based
•
•
•
Timestamps pointing to specific times in a list of data
Less accurate than Cursor
2 request parameters: since, until
132

133. Facebook
Graph API
Time-based Pagination
https://graph.facebook.com/me/home?access_token=…
&limit=5
Usage of since and until expressed as number of
seconds since January 1 1970 00:00:00 UTC
{
"data": [
{
"name": "Luke Skywalker",
"id": "100004245228110"
}
…
],
"paging": {
"previous": "https://graph.facebook.com/702008335/home?
limit=5&access_token=CAAK...&since=1386678619&__previous=1",
"next": "https://graph.facebook.com/702008335/home?
limit=5&access_token=CAAK...&until=1386675900"
}
}
133

134. Facebook
Graph API
Multiple objects at once
https://graph.facebook.com/?access_token=…
&ids=4,5,6
&fields=username
{
"4": {
"username": "zuck",
"id": "4"
},
"5": {
"username": "ChrisHughes",
"id": "5"
},
"6": {
"username": "moskov",
"id": "6"
}
}
134

135. Facebook
Graph API
Date & Locale
•
Dates
•
•
Add "date_format" request parameter to override
•
•
By default, ISO-8601
Syntax: http://php.net/manual/en/function.date.php
Locale
•
•
•
Add "locale" request parameter to override default
Syntax: https://www.facebook.com/translations/FacebookLocales.xml
For further information:
•
https://developers.facebook.com/docs/reference/api/dates/
•
https://developers.facebook.com/docs/reference/api/locale/
135

136. Graph API
Publishing
•
POST HTTP request
•
Access token required with right permissions
•
Examples
•
Post a status or a picture
•
Like something
•
Post comments
136

137. Graph API
Publishing
Basic Example
POST https://graph.facebook.com/me/feed?access_token=…
&message=This is a default message.
Every object:
https://developers.facebook.com/docs/graph-api/reference
{
"id": "702008335_10152142129743336"
}
137

138. Graph API
Publishing
Post a like
POST https://graph.facebook.com/702008335_10152142129743336/likes?
access_token=…
Like is a special case: it has no id.
true
138

139. Graph API
Publishing
Privacy
•
Add "privacy" parameter to post requests
•
•
•
Application privacy setting sets the ceiling for this value
Ex: if app is defined at FRIENDS, posting to public is not allowed).
Privacy can be set to:
•
•
ALL_FRIENDS: direct friends
•
FRIENDS_OF_FRIENDS: level 2
•
SELF : only me can see this (useful to test on real accounts)
•
•
EVERYONE: public
CUSTOM: in this case, it is possible to fine-tune (like with web interface)
Only applies to Posts to the user’s own timeline (ex: not applied to events)
139

140. Graph API
Publishing
Privacy Settings
140

141. Graph API
Publishing
Posting to friends
POST https://graph.facebook.com/me/feed?access_token=…
&privacy={"value":"ALL_FRIENDS"}
&message=This is a message to all of my friends.
{
"id": "702008335_10152142129743336"
}
141

142. Graph API
Publishing
Posting to Friends except a friend list
POST https://graph.facebook.com/me/feed?access_token=…
&privacy={
"value":"CUSTOM",
"allow":"ALL_FRIENDS",
"deny":"10150382806413336,10150382789648336"}
&message=This is a message with custom privacy.
These are ids of "acquaintances"
and "family" friend lists.
!
This can also be user ids to
exclude specific people.
{
"id": "702008335_10152142133908336"
}
142

143. Graph API
Publishing
Photos
•
2 ways:
•
Upload photo to the app’s album or an existing one
•
•
Create the app’s album if necessary. Album’s name is App name +
Photos.
Publish an existing web photo
•
Just from its URL
143

144. Graph API
Example - Publishing Photos (upload)
POST https://graph.facebook.com/me/photos?access_token=…
&privacy={"value":"ALL_FRIENDS"}
&message=Great city.
!
content-type: multipart/form-data; boundary=——WebKitFormBoundaryV…
…
———WebKitFormBoundaryV…
Content-Disposition: form-data; name="source"; filename="marseille.jpg"
Content-Type: image/jpeg
!
…
Id of the photo object.
Id of the post object.
HTTP Multipart request.
Behind the scene
(Postman will send this).
{
"id": "10152142262128336",
"post_id": "702008335_10152142255908336"
}
144

145. Graph API
Example - Publishing Photos (web)
POST https://graph.facebook.com/me/photos?access_token=…
&privacy={"value":"ALL_FRIENDS"}
&message=Great city.
&url=https://www.google.fr/images/srpr/logo11w.png
Facebook will download the photo.
Id of the photo object.
Id of the post object.
{
"id": "10152142286438336",
"post_id": "702008335_10152142255908336"
}
145

146. Graph API
Updating
•
POST HTTP request
•
Over simple: fields and value to update
•
Same permissions as publishing
146

147. Graph API
Updating
Basic Example
POST https://graph.facebook.com/702008335_10152143278443336?access_token=…
&message=This is a modified message.
Simply POST to the object.
Cannot update everything (ex: privacy)
true
147

148. Graph API
Deleting
•
DELETE HTTP request
•
Access token required with permissions.
•
Alternative: POST with "method=delete" parameter
148

149. Graph API
Deleting
Basic Example
DELETE https://graph.facebook.com/702008335_10152143278443336?access_token=…
!
or
!
POST https://graph.facebook.com/702008335_10152143278443336?access_token=…
&method=delete
true
149

150. Graph API
Deleting
Delete a like
DELETE
https://graph.facebook.com/702008335_10152143302288336/likes?access_token=…
Remember : like is not a root object.
true
150

151. Graph API
Searching
•
GET /search?q=…
•
Access token required
•
•
•
Pages & places: app access token
Others: user access token
No public Graph Search API yet
•
Example: "My friends that play Candy Crush Saga"
151

152. Graph API
Searching
Searchable Types
•
Post
•
Group
•
User
•
Checkin
•
Page
•
Place
•
Event
•
Location
!
!
152

153. Graph API
Searching
Example
GET https://graph.facebook.com/search?access_token=…
&q=fabrice delhoste
&type=user
{
"data": [
{
"name": "Fabrice Delhoste",
"id": "702008335"
}
],
"paging": {
"next": "https://graph.facebook.com/search?
type=user
&q=fabrice+delhoste
&access_token=CAAK…
&limit=5000
&offset=5000
&__after_id=702008335"
}
}
153

154. Facebook Graph API
Batch
•
Group requests together
•
More efficient
•
Several Graph API calls in a single HTTP request
154

155. Facebook Graph API
Batch
•
A set of HTTP requests/responses as JSON array
•
Can mix up to 50 requests with different access tokens or single shared access
token
•
GET, POST, and DELETE supported.
•
Multipart attachments (ex: photos)
•
Can depend on each other thanks to JSONPath
•
•
•
Selectively extract data from JSON structure with JSONPath subset.
JSONPath is a JSON query language. See http://goessner.net/articles/JsonPath/
Timeouts : null response (all or part) in JSON response
155

156. Facebook Graph API
Batch
Basic Example
POST https://graph.facebook.com/?access_token=…
Post to root /
batch=[
{ "method":"POST","relative_url":"me/feed", "body":"message=Happy"},
{ "method":"GET", "relative_url":"me/feed?limit=1"}
batch = HTTP Request Body
]
Post a status and read it immediately after (assuming no concurrent status).
[
{
"code": 200,
"headers": [
{"name": "Cache-Control","value": "private, no-cache, no-store, must-revalidate"},
…
],
"body": "{n
"id": "702008335_10152143594348336"n}"
},
{
"code": 200,
"headers": [
{"name": "Cache-Control","value": "private, no-cache, no-store, must-revalidate"},
…
],
"body": "{n
"data": [n
{n
"id": "702008335_643………………
}n}"
}
]
156

157. Facebook Graph API
Batch
Messy Example
POST https://graph.facebook.com/?access_token=…
batch=[
{ "method":"POST","relative_url":"me/feed",
"body":"message=Happy%26privacy=%257B%2522value%2522%253A%2522SELF%2522%257D"},
{ "method":"GET", "relative_url":"me/feed?limit=1"}
]
[
{
Double URL-encoding needed !!!
"code": 200,
"headers": [
{"name": "Cache-Control","value": "private, no-cache, no-store, must-revalidate"},
…
],
"body": "{n
"id": "702008335_10152143594348336"n}"
},
{
"code": 200,
"headers": [
{"name": "Cache-Control","value": "private, no-cache, no-store, must-revalidate"},
…
],
"body": "{n
"data": [n
{n
"id": "702008335_643………………
}n}"
}
]
157

158. Facebook Graph API
Batch
Advanced Example
By default, responses from request used as a
dependency (here ) are not returned to avoid overhead.
omit_response_on_success forces response.
POST https://graph.facebook.com/?access_token=…
batch=[
!
!
!
{
"method":"GET", "relative_url":"me/friends",
"name":"friends", "omit_response_on_success":false },
{
"method":"GET", "relative_url":"?ids={result=friends:$.data.*.id}" }
]
JSONPath expression.
Syntax: {result=requestname:<jsonpath>}
158

159. Facebook Graph API
Errors
{
"error": {
"message": "Message describing the error",
"type": "OAuthException",
"code": 190 ,
"error_subcode": 460
}
}
No official full documentation for error codes !!!
https://developers.facebook.com/docs/graph-api/using-graph-api/#errors
Google is your friend.
159

160. Facebook Graph API
Old REST API
•
Before Graph API
•
Absolutely not REST
•
https://api.facebook.com/method/{methodname}
•
Deprecated
•
Still in use in some apps.
160

161. Facebook Graph API
Practical Work
•
In Postman, create a new collection named "FB Graph API"
and build HTTP requests to:
•
Get your profile
•
Get the birthday of one of your friend
•
Get all of your friends’ birthday
•
Get 3 friend profiles at once
•
Get your 10 first friends
•
Get list from friend number 10 to friend number 20
161

162. Facebook Graph API
Practical Work
•
Get the photos of this album
•
Create a photo album with privacy SELF
•
Add a web photo to this album
•
Post a message with custom privacy (allow/deny some testers)
•
Like this post
•
Get this post metadata
162

163. Facebook Graph API
Practical Work
•
Get this post likes
•
Delete this like
•
Get your home newsfeed (homepage recent stream)
•
Get the messages of 50 latest newsfeed posts with their 3 last
comment messages
•
Run a full text search for a pattern in your newsfeed retrieving only
the message of the 5 first matches
163

164. Facebook Graph API
Practical Work
•
Create a secret event
•
Introspect this event
•
Invite other testers to this event
•
Ask one of the testers to attend the event
•
Get the list of attendees
164

165. Facebook Graph API
Practical Work
•
Upload a photo to this event with a short message
•
Get the event feed
•
Delete this event
•
Write a batch request to create and invite to an event at the same
time
165

166. Facebook
Facebook Query Language (FQL)

167. Facebook Query Language (FQL)
•
https://developers.facebook.com/docs/reference/fql
•
Limited SQL subset
•
•
One table, no JOIN, no LIKE, no COUNT(*), no GROUP BY, no star for multiple columns *,
More power than Graph API
•
•
•
Better filtering option
Access to more information (ex: friend requests)
Read-only virtual private database
!
•
Facebook actually exposes a database with more than 1 billion users !
167

168. Facebook Query Language (FQL)
Tables
album
app_role
application
apprequest
checkin
column
comment
comments_info
connection
cookies
developer
domain
domain_admin
event
event_member
family
friend
friend_request
friendlist
friendlist_member
group
group_member
insights
like
link
link_image_src
link_stat
location_post
mailbox_folder
message
note
notification
object_url
offer
page
page_admin
page_blocked_user
page_fan
page_global_brand_child
page_milestone
permissions
permissions_info
photo
photo_src
photo_tag
place
privacy
privacy_setting
profile
profile_pic
profile_tab
profile_view
question
question_option
question_option_votes
review
score
square_profile_pic
square_profile_pic_size
standard_friend_info
standard_user_info
status
stream
stream_filter
stream_tag
subscription
table
thread
translation
unified_message
unified_message_count
unified_message_sync
unified_thread
unified_thread_action
unified_thread_count
unified_thread_sync
url_like
user
video
video_tag
168

169. Facebook Query Language (FQL)
Query Syntax
select_expr can be a field or
a function of a field.
Cannot use * (star)
Only 1 table
Only 1 order
by expression
Offset-based
Pagination
SELECT select_expr [, select_expr ...]
FROM table_reference
WHERE where_condition
[ORDER BY {col_name | expr | position} [ASC | DESC]]
[LIMIT {[offset,] row_count | row_count OFFSET offset}]
where_condition is composed of:
!
Logical operators: OR, AND, NOT
IN (subquery)
IN (expr [, expr] …)
= != <> < > <= >=
+ - * /
Grouping with parenthesis ()
Functions (next slides)
169

170. Facebook Query Language (FQL)
Sending FQL Query
https://graph.facebook.com/fql?access_token=…
&q=SELECT name FROM user WHERE uid=me()
Obviously, the query must be URLencoded (not here for readability)
me() is the user authenticated
by the access_token
JSON result:
array of objects enclosed in data
{
"data": [
{
"name": "Tyrion Lannister"
}
]
}
170

171. Facebook Query Language (FQL)
Subqueries
My friends and me with
our square picture
SELECT name, pic_square FROM user WHERE
uid = me()
OR
uid IN (SELECT uid2 FROM friend WHERE uid1 = me())
User Id is IN the result
of the nested query
171

172. Facebook Query Language (FQL)
Pagination
SELECT name
FROM user
WHERE uid IN (SELECT uid2 FROM friend WHERE uid1=me())
LIMIT 10
10 first friends
172

173. Facebook Query Language (FQL)
Pagination
SELECT name
FROM user
WHERE uid IN (SELECT uid2 FROM friend WHERE uid1=me())
LIMIT 10,10
10 next friends
!
Identical to
LIMIT 10 OFFSET 10
173

174. Facebook Query Language (FQL)
Sending multiple queries at once
GET https://graph.facebook.com/fql?q={
"query1": "SELECT uid, rsvp_status
FROM event_member
WHERE eid=219790564859590",
"query2": "SELECT name, url, pic
FROM profile
WHERE id IN (SELECT uid FROM #query1)"
}
#query1 is a reference to the results of first
query (named "query1"). Use hash symbol
to reference.
Name your queries
{
Query 1: get the members invited to an event (12345678)
Query 2: get the profile details of the attendees
"data": [
{
"name": "query1",
"fql_result_set": [{"uid":702008335,"rsvp_status": "attending" } ]},
{
"name": "query2",
"fql_result_set": [
{ "name": "Fabrice Delhoste",
"url": "https://www.facebook.com/fabricedelhoste",
"pic": "https://fbcdn-profi…" }
] }
]
}
174

175. Facebook Query Language (FQL)
Data Types
•
string
•
unsigned int32
•
bool
•
struct
•
array<…>
•
object<…,…>
•
id
•
number
•
timestamp
•
list
•
int32
175

176. Facebook Query Language (FQL)
Indexable Columns
•
Every table has one or more index-able columns
•
IMPORTANT: FQL query MUST have at least one
index-able column in WHERE clause.
Marked with "magnifier" icon in
FQL reference documentation
176

177. Facebook Query Language (FQL)
Functions
•
me(): guess who?
•
now(): guess when?
•
rand(): random number
•
concat(…, …): concatenate
•
strlen(string): length of string
177

178. Facebook Query Language (FQL)
Functions
•
substr(string, start, length): substring
•
strpos(haystack, string): search string in haystack
•
Use it to achieve "LIKE"
•
upper(string): convert string to uppercase
•
lower(string): convert string to lowercase
•
distance(latitude, longitude, "float", "float"): used for
geolocation
178

179. Facebook Query Language (FQL)
Functions
SELECT concat(substr(first_name,0, 1), substr(last_name, 0, 1))
FROM user WHERE uid IN ( SELECT uid2 FROM friend WHERE uid1 = me())
Returns all friends’ initials.
anon is the result of the function
{
"data": [
{
"anon": "TL"
},
{
"anon": "JS"
},
…
179

180. Facebook Graph API
Practical Work
•
In Postman, create a collection named "FB FQL" and build HTTP requests to:
•
Get my profile (hometown, birthday, …)
•
Get my last status
•
Get all of my events
•
Get all photos I’m tagged into
•
List friends sorted by their name length
•
Search friend from a pattern
•
Find and order the 10 friends with highest number of mutual friends
•
Find name of online friends
180

181. Facebook Graph API
Practical Work
•
Get your unread notifications (simulate them)
•
Get pages and their number of fans I’m following (look to connection table)
•
Get all photos from latest modified album from most recent to oldest
•
Find name of all friends but family
•
Find all singles out of your friends
•
Write a batch that finds singles and post "Hello" concatenated with all of their
first names
•
Get latest one-week photos from all of your friends (most recent first)
•
Get each friend list your friends belongs to (for each friend)
181

182. Facebook
Developer Tools

183. Test Users
Facility to create fake users for testing purposes

184. Facebook Developer Tools
Test Users?
•
https://developers.facebook.com/docs/test_users/
•
Used for development and debugging purposes
•
Test Users = Fake Users
•
•
•
Avoid confusing with Testers = Real Users !!!
Invisible, no interaction with real users
2000 test users per app max.
184

185. Facebook Developer Tools
Test Users
Creating and Deleting Test Users (GUI)
Testers = Real Users
Test Users = Fake Users

186. Facebook Developer Tools
Test Users
Getting Test Users
GET https://graph.facebook.com/760835680597440/accounts/test-users?
access_token=…
App access token
{
"data": [
{
"id": "100007272790057",
"access_token": "CAAKzZBdx5…",
"login_url": "https://www.facebook.com/platform/
test_account_login.php?user_id=100007272790057&n=FlFJkyssketSX9Y"
},
…
}
186

187. Facebook Developer Tools
Test Users
Creating a test user (API)
GET https://graph.facebook.com/760835680597440/accounts/test-users?
&access_token=…
app id
&name=Tyrion Lannister
&locale=en_US
&installed=true
&permissions=read_stream
Is the application installed to this user at creation?
&method=post
If installed=true, these are the
permissions given to the application.
login_url allows direct login (no password).
{
"id": "100007176673155",
"email": "tyrion_jihlktz_lannister@tfbnw.net",
"access_token": "CAAKzZBdx5…",
"login_url": "https://www.facebook.com/platform/
test_account_login.php?user_id=100007176673155&n=tR7yCoyWqEw1Wfu",
"password": "1890805985"
}
187

188. Facebook Developer Tools
Test Users
Deleting a test user
https://graph.facebook.com/100007176673155?
access_token=…
User access token or app access token
true
188

189. Facebook Developer Tools
Test Users
Update Test Users username and password
GET https://graph.facebook.com/100007176673155?
&access_token=…
&password=thrones
&name=Cersei Lannister
&method=post
true
189

190. Facebook Developer Tools
Test Users
Making Friends
POST (friend request)
https://graph.facebook.com/100007176673155/friends/100007272790057?
access_token=…
!
then
!
POST (friend confirmation)
https://graph.facebook.com/100007272790057/friends/100007176673155?
access_token=…
User access token (the user to add friend to)
true
190

191. Facebook Developer Tools
Test Users
Adding test users to other apps
GET https://graph.facebook.com/APP_ID/accounts/test-users?
installed=true
&permissions=read_stream
&uid=TEST_USER_ID
&owner_access_token=…
&access_token=…
&method=post
App access token to add the user from
App access token to add the user to
true
191

192. Facebook Developer Tools
Test Users
Practical Work
•
In Postman, create a "FB Test Users" collection where
you build HTTP requests to:
•
Create 3 test users: Bob, Joe, and Larry
•
Make Bob friend with Joe
•
Request Larry to be friend with Joe
•
Use Graph API Batch to get friends and friendrequests
•
Use Graph API Batch to delete them all
192

193. Facebook
Support & Maintenance

194. Roadmap
•
developers.facebook.com/roadmap/
Review frequently.
194

195. Breaking Changes and Migration Policy
•
90-day breaking change policy.
•
Breaking change automatically enabled for new apps.
•
Recommendation: asap !
•
TODO : App Dashboard / Migration
195

196. Platform Status
•
developers.facebook.com/live_status/
JSON
Events
History
196

197. Bugs
•
developers.facebook.com/bugs/
Subscribe to bugs
(email alert)
Communicate with
Facebook
Problem
description
197

198. Beta Tier
•
developers.facebook.com/docs/support/beta-tier/
•
Desktop: www.beta.facebook.com
•
Mobile Web: m.beta.facebook.com
•
Apps in Canvas: apps.beta.facebook.com
•
Graph API: graph.beta.facebook.com
•
Code changes:
•
Beta on Sunday evenings (Pacific time)
•
Production on Tuesday evenings
198

199. Stay tuned
developers.facebook.com/blog
@FacebookDevRel
@fb_engineering
199

200. Facebook
Chat API

201. Facebook Chat API
•
https://developers.facebook.com/docs/chat/
•
XMPP
•
•
•
eXtensible Messaging and Presence Protocol
Custom with limitations. Ex: authentication, presence, …
Use one of the numerous XMPP client framework
•
Ex: Smack in Java
Not (yet?) covered in this course.
201

202. Facebook
Open Graph

203. Open Graph
Object and Action Model
•
Facebook internal graph have limited interactions
•
•
Open Graph turns any web page into an object
Object and Action model
Not (yet?) covered in this course.
203

204. Facebook
Real-time Updates

205. Facebook Realtime Updates
•
Push model
•
•
Subscribe to data changes
•
•
vs Polling model
Facebook calls your server with POST request
Caching data
•
Ex: synchronize friend information
205

206. Facebook Realtime Updates
Publicly Supported Objects
•
User
•
Limited to: feed, friends, activities, interests, music, books, movies,
television, likes, checkins, location, events.
•
Permissions
•
Payments and Payment Subscriptions
•
Errors
•
Page
•
Limitations
206

207. Facebook Realtime Updates
Dashboard
•
With recent new dashboard, FB removed the panel !!!
•
Workaround: https://developers.facebook.com/apps/{appId}/
realtime?ref=nav
207

208. Facebook Realtime Updates
Dashboard
208

209. Facebook Realtime Updates
How to proceed
•
3 steps
•
Register your server (dashboard or API)
•
Respond correctly to a ping GET request
•
Starts listening for POST requests
209

210. Facebook Realtime Updates
API
•
https://graph.facebook.com/{appId}/subscriptions
•
Listing subscriptions : GET
•
Adding or modifying subscriptions : POST
•
Query parameters:
•
•
callback_url : our server endpoint
•
•
fields : a comma-separated list of object properties to be updated about
•
•
object : the object to be updated about
verify_token : a verify token sent to our server
Will send GET request to callback_url in order to validate your server
Deleting subscriptions : DELETE
210

211. Facebook Realtime Updates
Your Callback Server
•
Two endpoints needed:
•
•
•
Subscription Verification
Receiving Updates
HTTPS preferred
211

212. Facebook Realtime Updates
Your Callback Server
Subscription Verification
•
Query parameters
•
•
hub.challenge: random
•
•
hub.mode : "subscribe"
hub.verify_token: defined at subscription
Verify hub.verify_token
•
•
Check origin is Facebook
Return hub.challenge in the response
•
Prevents DDoS
212

213. Facebook Realtime Updates
Your Callback Server
Subscription Verification
http://mycallbackserver.com/?hub.mode=subscribe
&hub.challenge=677173267
&hub.verify_token=thisisme
Verify the token. If OK, echoes the
challenge back to Facebook to validate
the registration.
677173267
213

214. Facebook Realtime Updates
Your Callback Server
Receiving Updates
•
JSON
•
No content, only notification about content
•
Request needed to get details (Graph API or FQL)
•
Example: notified about changes to ‘friends’ field
•
Batch updates: possibly multiple notifications at once
•
Retry policy
•
Payload signed in HTTP header
•
SHA-1 Signature in HTTP header named ‘X-Hub-Signature’
214

215. Facebook Realtime Updates
Your Callback Server
Receiving Updates
POST http://mycallbackserver.com/
!
{
}
"object":"user",
"entry":[
{ "uid":"100001555554986",
"id":"100001555554986",
"time":1387128215,
"changed_fields":["hometown"]
}
]
Here’s the fields that have been updated.
If you need details, you can use Graph
API or FQL.
215

216. Facebook Realtime Udates
Practical Work
•
If this is possible for your network (NAT, tunnel, reverse proxy…),
implement a Java servlet:
•
Responding to RTU ping
•
Simulate and start receiving updates for user updates such as hometown
•
•
Bonus: verify signature :-)
Get the user’s new hometown
•
Register it to RTU
•
In Postman, create a HTTP Collection named "RTU Facebook"
•
Write all HTTP requests to subscribe/unsubscribe/list RTU
216

217. Twitter

218. Twitter
Overview

219. Twitter
•
Founded in 2006
•
Jack Dorsey, Evan Williams, Biz
Stone, and Noah Glass
•
232 million monthly active users.
•
100 million daily active users.
•
176 million mobile users.
•
More than 340 millions tweets daily.
219

220. Twitter?
•
Social network and microblogging
•
Real-time information network
•
Ad network
•
Search engine
•
Identity provider across the web and mobile apps
220

221. Twitter
Features
•
Tweet (140 chars message)
•
Mention
•
Timeline
•
Lists
•
Follow
•
Direct Message
•
Favorite
•
Search and Discover
•
Trending topics
•
Twitter Cards
•
Retweet
•
Twitter buttons
•
Hashtag
221

222. Twitter
Features
Interactions
Following
&
Followers
Personalized Content
Profile
Direct Message
Go to Settings
Post a tweet
Search
Suggestions
Home Timeline
Trends

223. Twitter
Tweet?
Twitter
account
Text
Hyperlink
Mention
Hashtag
Tweet to reply
Copy/paste to
your followers
Mark as
favorite

224. Twitter
Concerns
•
Sustainability
•
Competitors
•
Facebook
•
Google
•
Whatsapp?
•
…
224

225. Twitter
References
•
www.twitter.com
•
dev.twitter.com
225

226. Twitter
Platform

227. Twitter
Platform?
•
A real-time messaging infrastructure
•
•
•
Develop applications on top of Twitter APIs
Access data in Twitter
For:
•
External websites
•
Devices and Mobiles apps
227

228. Twitter Platform
APIs
•
Current release: 1.1
•
REST API
•
•
Poll-based system - pseudo real-time
Streaming API
•
Long-lived real-time connections
•
Authentication: mostly oAuth 1.0
•
JSON
228

229. Twitter Platform
Objects
Metadata and contextual
information
(extracted hashtags, urls,
media, mentions, …)
229

230. Twitter Platform
Objects
Tweets
•
{
https://dev.twitter.com/docs/platform-objects/tweets
Beware of the accuracy on id (ex: in
"created_at": "Sun Dec 15 12:13:22 +0000 2013",
"id": 412193666464489472,
Javascript). Prefer id_str if they are different.
"id_str": "412193666464489472",
"text": "The old adage that "People are hired for their talents and fired for their
behavior" is true. http://t.co/evY73iGtyI",
"source": "<a href="http://www.socialflow.com" rel="nofollow">SocialFlow</a>",
"truncated": false,
"in_reply_to_status_id": null,
"in_reply_to_status_id_str": null,
"in_reply_to_user_id": null,
"in_reply_to_user_id_str": null,
"in_reply_to_screen_name": null,
Contains user’s details. See User object.
"user": { … },
"geo": null,
"coordinates": null,
Location. See Place object.
"place": null,
"contributors": null,
"retweet_count": 40,
Contains metadata of this tweets such as hashtags,
"favorite_count": 30,
urls, …
"entities": { … },
"favorited": false,
See Entities object.
"retweeted": false,
"possibly_sensitive": false,
"lang": "en"
230
}

231. Twitter Platform
Objects
Users
•
https://dev.twitter.com/docs/platform-objects/users
"user": {
"id": 13348,
"id_str": "13348",
"name": "Robert Scoble",
"screen_name": "Scobleizer",
"location": "Half Moon Bay, California, USA",
"description": "@Rackspace's Startup Liaison Officer, who grew up in Silicon Valley,
brings you technology news, videos, and opinions.",
"url": "http://t.co/EIFG1Db6U8",
"entities": { … },
Metadata extracted from user’s
"protected": false,
description. See Entities object.
"followers_count": 371652,
"friends_count": 40759,
"listed_count": 23418,
"created_at": "Mon Nov 20 23:43:44 +0000 2006",
"favourites_count": 56779,
"utc_offset": -28800,
"time_zone": "Pacific Time (US & Canada)",
"geo_enabled": true,
"verified": true,
"statuses_count": 65327,
"lang": "en",
…
},
231

232. Twitter Platform
Objects
Entities
•
https://dev.twitter.com/docs/platform-objects/entities
"entities": { "hashtags": [], "symbols": [],
"urls": [
{
"url": "http://t.co/h6IsNNn3n7",
"expanded_url": "http://j.mp/1ctMGrZ",
"display_url": "j.mp/1ctMGrZ",
"indices": [103,125]
}
],
"user_mentions": [
{
"screen_name": "FastCoLabs",
"name": "FastCoLabs",
"id": 1114932710,
"id_str": "1114932710",
"indices": [3,14]
},
{
"screen_name": "johnpaul",
"name": "John Paul Titlow",
"id": 3144021,
"id_str": "3144021",
"indices": [129,138]
}
]
}
Indexes of the string in the text
associated to this URL
232

233. Twitter Platform
Objects
Places
•
https://dev.twitter.com/docs/platform-objects/places
"place":
{
"attributes":{},
"bounding_box":
{
"coordinates":
[[
[-77.119759,38.791645],
[-76.909393,38.791645],
[-76.909393,38.995548],
[-77.119759,38.995548]
]],
"type":"Polygon"
},
"country":"United States",
"country_code":"US",
"full_name":"Washington, DC",
"id":"01fbe706f872cb32",
"name":"Washington",
"place_type":"city",
"url": "http://api.twitter.com/1/geo/id/01fbe706f872cb32.json"
}
233

234. Twitter Platform
Terms & Conditions
•
It’s free!
•
Twitter has the right to blacklist your application
•
Twitter has rate limits
•
Twitter has the right to change the rights
•
…it’s free!
234

235. Facebook Platform
API Limitations
•
API is very open…but also rate-limited.
•
See https://dev.twitter.com/docs/rate-limiting/1.1 for
global policy.
•
•
Caching, prioritize active users, fair use, streaming api, …
Each API function has documented rate-limits
•
https://dev.twitter.com/docs/rate-limiting/1.1/limits
•
Depending on the authentication (user or app)
235

236. Twitter Platform
Creating and Configuring an Application

237. Twitter Platform
Creating and configuring an application
Used during oath callback for access token
237

238. Twitter Platform
Creating and configuring an application
Consumer Key and Consumer Secret.
Never reveal Consumer Secret !
238

239. Twitter Platform
Creating and configuring an application
Permissions
239

240. Facebook Graph API
Practical Work
•
Create a Twitter account
•
Create your own Twitter application
•
Full access
•
Define oauth_callback url to whatever is supposed to be your
server (we won’t develop our server in this training)
240

241. Twitter
Authentication & Authorization

242. Twitter Authentication & Authorization
•
oAuth 1.0 - access token used in request signatures
•
Application-user authentication
•
•
•
to read/write on behalf of a Twitter user
oAuth 1.0a - requests are signed
Application-only authentication
•
•
•
to read/write on behalf of a Twitter application
oAuth 2 (client credentials grant)
Tokens do not expire
•
Except when user revokes your application or Twitter suspends your application
242

243. Twitter Authentication & Authorization
Application-user Authentication

244. Twitter Authentication & Authorization
Application-user Authentication
How to sign
•
How to sign user-level requests?
•
Make HTTP verb uppercase
•
Percent encode URL and every query parameters including oauth_*
•
•
Sort this list alphabetically by encoded key+value and concatenate
•
•
See https://dev.twitter.com/docs/auth/percent-encoding-parameters
payload = "{uppercase http verb}&{encoded url}&{encoded key}={encoded value}&{encoded key}
={encoded value}&…"
Compute signature:
•
key = {consumer_secret}&{oauth_token_secret}
•
HMAC-SHA1(key, payload)
244

245. Twitter Authentication & Authorization
Application-user Authentication
Payload to sign
POST&https%3A%2F%2Fapi.twitter.com%2F1%2Fstatuses
%2Fupdate.json&include_entities%3Dtrue%26oauth_consumer_key
%3Dxvz1evFS4wEEPTGEFPHBog%26oauth_nonce
%3DkYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg
%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp
%3D1318622958%26oauth_token%3D370773112GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb%26oauth_version
%3D1.0%26status%3DHello%2520Ladies%2520%252B%2520Gentlemen%252C
%2520a%2520signed%2520OAuth%2520request%2521
This is an example of a payload to sign
245

246. Twitter Authentication & Authorization
Application-user Authentication
Signature example
POST /1/statuses/update.json?include_entities=true HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization:
OAuth oauth_consumer_key="xvz1evFS4wEEPTGEFPHBog",
oauth_nonce="kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg",
oauth_signature="tnnArxj06cWHq44gCs1OSKk%2FjLY%3D",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1318622958",
oauth_token="370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb",
oauth_version="1.0"
Content-Length: 76
Host: api.twitter.com
!
status=Hello%20Ladies%20%2b%20Gentlemen%2c%20a%20signed%20OAuth%20request%21
After signature
246

247. Twitter Authentication & Authorization
Application-user Authentication
Authorization Header Details
•
Authorization HTTP Header contains:
•
oauth_consumer_key: API key, found in Twitter application dashboard
•
oauth_nonce: random and unique for every request (anti-replay)
•
oauth_signature: cryptographic signature of the request
•
oauth_signature_method: currently HMAC-SHA1
•
oauth_timestamp: seconds since epoch
•
oauth_token: the user access token previously obtained
•
oauth_version: currently 1.0
247

248. Twitter Authentication & Authorization
Application-user Authentication
Obtaining access token
•
To obtain a user access token
•
•
Interact with the user
•
•
Get a request token
Exchange code for access token from server
Used to interact on behalf of a user
248

249. Twitter Authentication & Authorization
Application-user Authentication
Step 1 - Get a request token
POST https://api.twitter.com/oauth/request_token
Content-type: application/x-www-form-urlencoded
Authorization: OAuth realm="https%3A%2F%2Fapi.twitter.com",
oauth_consumer_key="LGYbJs9HKa7PgovBM92uQ",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1386164583",
oauth_nonce="8MWKpm",
oauth_version="1.0",
URL encoded
Must be defined in
oauth_signature="jsrz82u61LrG0QeaRNDx0emXyLY%3D"
Dashboard Settings
!
oauth_callback=http%3A%2F%2Ffabrice.delhoste.com
oauth_token: here’s the request token to use for step 2 & 3
oauth_token_secret: used in signature computation for step 3
WARNING: In POSTMAN oAuth 1.0,
token and token secret must remain
empty for now.
oauth_token=yWaXUQ8jxdlw7nAGbfdWFiUeJK9qeTD2dDhvJVWGc
&oauth_token_secret=Lbx2VlADy9wZfhOyzKa4ukeSXSRUEcXoyvGAZOAwSg
&oauth_callback_confirmed=true
249

250. Twitter Authentication & Authorization
Application-user Authentication
Step 2 - User interaction
In browser (GET):
https://api.twitter.com/oauth/authenticate?
oauth_token=yWaXUQ8jxdlw7nAGbfdWFiUeJK9qeTD2dDhvJVWGc
Request token
"authorize" might be used if you want the user to confirm every
time. If not, authenticate can be used only if enabled in
dashboard:
oauth_verifier is used to assess the user has taken part of an
application approval process
Redirected to:
http://fabrice.delhoste.com/?
oauth_token=yWaXUQ8jxdlw7nAGbfdWFiUeJK9qeTD2dDhvJVWGc
&oauth_verifier=Gmm1McgeK19qlP2zneLb2akKpgP9t2n0oc8GuWq3cZ8
250

251. Twitter Authentication & Authorization
Application-user Authentication
Step 3 - Exchange request token for an access token
POST https://api.twitter.com/oauth/access_token
Authorization:
OAuth realm="https%3A%2F%2Fapi.twitter.com",
oauth_consumer_key="LGYbJs9HKa7PgovBM92uQ",
oauth_token="yWaXUQ8jxdlw7nAGbfdWFiUeJK9qeTD2dDhvJVWGc",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1386287051",
oauth_nonce="ZWTbrv",
oauth_version="1.0",
oauth_signature="2Um29j9BNg94FmkKimtj3ZVMbxg%3D"
!
oauth_verifier: Gmm1McgeK19qlP2zneLb2akKpgP9t2n0oc8GuWq3cZ8
WARNING: now, in POSTMAN oAuth 1.0, token must be
set for signature.
oauth_token=18229030-6lOPdgeL0rqluEeajCVOyMLoU2i0I4d8HfvOJBguA
&oauth_token_secret=F1C3DUHjMii8Z6VWPl5BqaMrEGvRcislkQzBKB446zAM7
&user_id=18229030
&screen_name=spifd
251

252. Twitter Authentication & Authorization
Application-only Authentication

253. Twitter Authentication & Authorization
Application-user Authentication
How to sign
•
How to sign application-level requests?
•
Use Authorization HTTP header with bearer token:
•
Ex: Authorization: Bearer AAAAAA…
Bearer token
253

254. Twitter Authentication & Authorization
Application-only Authentication
Obtaining access token
•
To obtain a application-only access token (bearer token):
•
•
POST to /oauth2/token with HTTP Basic authentication using
consumer key as login and consumer secret as password
Used to interact on behalf of an application
•
Ex: search tweets
254

255. Twitter API - Authentication & Authorization
Application-only Authentication
Obtaining an Application Access Token
POST https://api.twitter.com/oauth2/token
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
NmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=client_credentials
Base64( urlencode({consumerKey}) + ":" + urlencode({consumerSecret}) )
Ex: base64(xvz1evFS4wEEPTGEFPHBog:L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg)
!
In Postman, simply use HTTP Basic authentication filling login and password accordingly
{“access_token”:”AAAAAAAAAAAA…",
"token_type":"bearer"}
255

256. Twitter API - Authentication & Authorization
Application-only Authentication
Revoking an Application Access Token
POST https://api.twitter.com/oauth2/invalidate_token
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
NmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
access_token=AAAAAAAAAAAA…
The bearer token to invalidate.
Warning: Postman url-encodes.
{
"access_token": “AAAAAAAAAAAAA…”
}
256

257. Twitter API Console by APIGee
Explore Twitter API easily

258. Twitter
API Console
•
https://dev.twitter.com/console (provided by Apigee)
258

259. Twitter Authentication & Authorization
Practical Work
•
In Postman and your browser, build a "Twitter Auth"
collection of HTTP requests to:
•
Get an Application-user access token
•
Get an Application-only access token
•
Invalidate an Application-only access token
259

260. Twitter
REST API

261. Twitter REST API ?
•
https://api.twitter.com/
•
Current release: 1.1
•
Get data in and out of Twitter.
•
•
Read, Publish, Delete, Search
Authentication: oAuth 1.0
!
Note: in next slides, oAuth 1.0 signatures are omitted
to ease readability
261

262. Twitter
REST API
•
Resources-oriented
•
•
•
Every object has a unique identifier
All data returned as JSON (or XML)
Resources : https://api.twitter.com/1.1/{...}
262

263. Twitter
REST API
Resources
Timelines
Tweets
Search
Streaming
Direct
Messages
Friends &
Followers
Saved
Searches
Users
Places &
Geo
Suggested
Users
Favorites
Lists
OAuth
Help
Trends
Spam
Report
263

264. Twitter
REST API
Reading
•
GET
•
Permissions applied (access token)
•
Response: JSON
•
Timelines
•
•
User timeline
•
•
Home timeline
Retweets and Mentions
Tweets, Retweets, Retweeters, Direct Messages, Friends & Followers,
Suggested Users, Favorites, Lists, ……. mostly everything you dream of.
264

265. Twitter
REST API
Home Timeline
https://api.twitter.com/1.1/statuses/home_timeline.json
[
{
"created_at": "Sun Dec 15 10:11:57 +0000 2013",
"id": 412163108439072800,
"id_str": "412163108439072768",
"text": "Goodbye Car Lanes: Madrid Wants To Take Back Streets For Pedestrians http://t.co/8b1iwNqYRS",
"source": "<a href="http://www.socialflow.com" rel="nofollow">SocialFlow</a>",
"truncated": false,
"in_reply_to_status_id": null,
"in_reply_to_status_id_str": null,
"in_reply_to_user_id": null,
"in_reply_to_user_id_str": null,
"in_reply_to_screen_name": null,
"user": {
"id": 2735591,
"id_str": "2735591",
"name": "Fast Company",
"screen_name": "FastCompany",
"location": "New York, NY",
"description": "Official Twitter feed for the Fast Company business media brand; inspiring readers to
think beyond traditional boundaries & create the future of business.",
"url": "http://t.co/LVE88WcJTX",
"entities": {
…
},
…
265

266. Twitter
REST API
Pagination
•
count: maximum number of tweets to get (up to count)
•
max_id and since_id parameters
•
max_id: tweets lower than or equal to this id
•
since_id: new tweets since this id
266

267. Twitter
REST API
Pagination with max_id
•
max_id : tweets lower than or equal to this id
Problem: page consistency
Typical offset-based cursor
problem: 2 new tweets, my
page shifts
Solution: use max_id
max_id brings consistency whatever
happens in the meantime
267

268. Twitter
REST API
Pagination with since_id
•
since_id : tweets greater than this id
Best: combine since_id and max_id
Imagine I have already
processed tweet 9 and 10
I don’t want them again !
consistent paging
268

269. Twitter
REST API
Example
https://api.twitter.com/1.1/statuses/home_timeline.json?
&count=5
Get 5 latest tweets
Last tweet from result
[
…
…
…
…
…
…
…
!
{
"created_at": "Sun Dec 15 12:22:45 +0000 2013",
"id": 412196025378820096,
"id_str": "412196025378820096",
"text": ".@Jeff Clavier #Kimaday presentationnThings startups need to know if they want to raise
capital from Silicon Valley: http://t.co/xZVZW6wdP6",
"source": "<a href="http://bitly.com" rel="nofollow">bitly</a>",
"truncated": false,
"in_reply_to_status_id": null,
…
}
]
269

270. Twitter
REST API
Example
https://api.twitter.com/1.1/statuses/home_timeline.json?
&max_id=412196025378820095
&count=5
Id-1 of the last tweet
[
{
"created_at": "Sun Dec 15 12:13:22 +0000 2013",
"id": 412193666464489472,
"id_str": "412193666464489472",
"text": "The old adage that "People are hired for their talents and fired for their behavior" is
true. http://t.co/evY73iGtyI",
"source": "<a href="http://www.socialflow.com" rel="nofollow">SocialFlow</a>",
"truncated": false,
"in_reply_to_status_id": null,
"in_reply_to_status_id_str": null,
"in_reply_to_user_id": null,
"in_reply_to_user_id_str": null,
"in_reply_to_screen_name": null,
"user": {
"id": 2735591,
"id_str": "2735591",
"name": "Fast Company",
"screen_name": "FastCompany",
"location": "New York, NY",
…
…
270

271. Twitter
REST API
Publishing
•
POST with specific URL path
•
Access token required with permissions.
271

272. Twitter
REST API
Tweet !
POST https://api.twitter.com/1.1/statuses/update.json
Content-Type: application/x-www-form-urlencoded
Body: must be URL-encoded
status=Hello http://www.yahoo.fr
{
"created_at": "Sun Dec 15 21:41:34 +0000 2013",
Automatic URL shortener
"id": 412336655019028480,
"id_str": "412336655019028480",
"text": "Hello http://t.co/YZjB4ccR4b",
"source": "<a href="http://www.changeitlater.com" rel="nofollow
">Training-API</a>",
"truncated": false,
"in_reply_to_status_id": null,
"in_reply_to_status_id_str": null,
"in_reply_to_user_id": null,
Returns the newly created tweet.
"in_reply_to_user_id_str": null,
"in_reply_to_screen_name": null,
"user": {
…
272

273. Twitter
REST API
Deleting
•
POST with specific URL path
•
•
•
Not DELETE
Not a query parameter
Access token required with permissions.
273

274. Twitter
REST API
Delete a tweet
POST https://api.twitter.com/1.1/statuses/destroy/
412342464415301632.json
{
"geo": null,
"in_reply_to_user_id_str": null,
"user": {
"is_translator": false,
"contributors_enabled": false,
"profile_background_tile": false,
"name": "TestSpi",
"listed_count": 0,
"lang": "en",
"profile_sidebar_fill_color": "DDEEF6",
"statuses_count": 5,
…
274

275. Twitter
REST API
Searching
•
Search for tweets
•
•
Fine-grained search based on location, language, …
Search for users
•
Pagination with page & count parameters
•
Search for places
•
Save search
•
Trends
275

276. Twitter REST API
Searching tweets
GET https://api.twitter.com/1.1/search/tweets.json?q=iphone
{
"statuses": [
{
"metadata": {
"result_type": "recent",
"iso_language_code": "ru"
},
"created_at": "Tue Dec 17 16:31:16 +0000 2013",
"id": 412983343559745536,
"id_str": "412983343559745536",
"text": "Допрос iPhone 5s: плюсы и минусы нового
смартфона",
"source": "<a href="http://c-ya.org/" rel="nofollow
">TwitApplet</a>",
"truncated": false,
276

277. Twitter REST API
Searching users
https://api.twitter.com/1.1/users/search.json?q=lady&count=2
[
{
Pagination with count and page
parameters (see doc)
"id": 14230524,
"id_str": "14230524",
"name": "Lady Gaga",
"screen_name": "ladygaga",
"location": "real life gypsy",
"description": "A pop star from the 70's trapped in 2013. r
nrn'You are a legend. Make a sculpture of you. Self-invention
matters. You are the artist of your own life.' -#ARTPOP",
"url": null,
"entities": {
"description": {
"urls": []
}
},
277

278. Twitter REST API
Practical Work
•
Create a "Twitter API" collection where you create HTTP
requests to:
•
Get your Twitter timeline
•
Get 20 latest tweets from your timeline
•
Get next 10 next tweets
•
Get your timeline reducing payload just to the tweets
•
Post a tweet
•
Delete a tweet
278

279. Twitter REST API
Practical Work
•
Favorite a tweet
•
Search tweets on behalf of an application
•
Search tweets on behalf of a user
279

280. Twitter
Streaming API

281. Twitter
Streaming API
•
https://dev.twitter.com/docs/streaming-apis
•
Receives realtime push data
•
Long-lived HTTP request
•
Never ending request
•
Parse response incrementally
281

282. Twitter
Streaming API
Streams
•
Public Streams
•
•
User Streams
•
•
Monitoring and collecting public data.
Single user stream. Usually client-side.
Site Streams
•
Multiple user stream at once. Server-side.
282

283. Twitter
Streaming API
Public Streams
•
Subscribing to public data
•
•
Track keywords
•
•
Track public accounts
Track geolocated tweets
1 single connection
283

284. Twitter
Streaming API
User Streams
•
Subscribing to realtime updates on behalf of a single
authenticated user
•
User himself/herself or following
•
Track keywords
•
Track geolocated tweets
•
Limited to a few connections
•
Do not use server-side
•
That would require too many connections
284

285. Twitter
Streaming API
Site Streams
•
Subscribing to realtime updates for a large number of
users
•
Restricted (whitelist demand)
•
Limited Beta
285

286. Twitter
Streaming API
Practical Work
•
Use Netbeans to create a simple Maven Java console application project
•
Use Twitter Hosebird Client (hbc) to connect to your user stream
•
•
Add as Maven dependency (pom.xml)
•
WARNING: this is rate-limited (error 420). Don’t connect too often till you’re sure about your code.
•
•
https://github.com/twitter/hbc
WARNING: current hbc implementation does not handle HTTP proxy - Fork and fix it in ClientBuilder class
Use Apache HttpClient to cross post your tweets to a Facebook test user as they are received
•
•
Add as Maven dependency (pom.xml)
•
•
http://hc.apache.org/httpcomponents-client-4.3.x/quickstart.html
Put a hard-coded access token
Open your browser to both test user and Twitter to check
•
Follow temporarily someone active to generate tweets
286

287. Twitter
Developer Tools

288. Twitter
Support & Maintenance