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.
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
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
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
13. HTTP
•
Application protocol for distributed hypermedia systems.
•
Request / response
•
Stateless
•
Media independent
•
Foundation of the WWW
•
Current version: 1.1
13
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
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
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
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
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
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
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
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
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
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
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
59. Social Network
•
A platform to handle social interactions between actors
•
People, Community, and Companies
•
Sharing Interests and Activities
•
Communications
59
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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