1. Kirsten Jones, Technical Leader, Cisco Systems
Demystifying REST

2. Who’s this talk for? Application Developers …Curious about using REST
…Wanting help debugging the system
Not REST API Architects (sorry!)

3. What Will I Cover? HTTP Overview REST Web Services
OAuth Authentication Basics
REST Debugging

4. HTTP – Protocol for the Web
HyperText Transfer Protocol
Used for conversations between web clients and servers
Most of the internet uses HTTP
Supports verbs for GET, PUT, POST, DELETE
Query parameter framework

5. How does HTTP Work? Client sends a request
Method
URL
Headers
(sometimes) parameters
(sometimes) body
Server replies with a response
Content
Status

6. What do you Mean, Status? HTTP response codes for dummies.
50x: we fucked up.
40x: you fucked up.
30x: ask that dude over there.
20x: cool.
Props for this

7. Headers vs. Parameters Headers Parameters
Generally meta-information about the request
For instance: requesting an image in a specific format
Parameters
Limit or describe how you want the resource (searches, filters)
Defines the resource you’re requesting

8. Request and Response Headers
Request (client)
Accept: Give me this kind of response. Here’s a list in order of what I’m hoping you’ll send. Accept: text/html,application/xhtml+xml,application/xml
Response (server)
Content-Type: This is the kind of response I’m sending you. Content-Type: text/html; charset=UTF-8

9. Parameters Part of the URL
Everything after the question mark, delimited by ampersands

10. An example request Chrome browser sends a request to Google
Method: GET
URL:
Headers:
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.8
Accept-Charset: ISO ,utf-8;q=0.7,*;q=0.3
Connection: keep-alive
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_3) AppleWebKit/ (KHTML, like Gecko) Chrome/ Safari/535.19
Accept-Encoding: gzip,deflate,sdch
Cookie: NID=59=EudJ2a15ql8832PCysQA0qchtuvGWMoA7rkp79VpIYAQ8-j42IO17LFudCYNMXm9l6SHcu3YgrGRCdrRCyM468xPZaOek4Pi-AXQ8eARqU1SGYx6y7_9LW-c3HHb-vs2; PREF=ID=994f8de0e8b39a5b:U=237805f1f710dc73:FF=0:TM= :LM= :S=W0Hha7x4czdXp51U
Host:

11. Example Response Google sends a response Headers:
Content-Length: 24716
Content-Encoding: gzip
Set-Cookie: NID=59=F48kbwfwOi-qCHJyrnMSUlDBVxK-ZVKZpq5B5jttt_25IRN4lS-0rQcVttq-dnOIlQzafw1i4HPQAO0RpZ7NuC0WCKWta7SYoekx0--YGf2zIFZ9VXIKS-_UEaOH9iBe; expires=Sat, 10-Nov :26:46 GMT; path=/; domain=.google.com; HttpOnly
Expires: -1
Server: gws
X-XSS-Protection: 1; mode=block
Cache-Control: private, max-age=0
X-Frame-Options: SAMEORIGIN
Content-Type: text/html; charset=UTF-8
Date: Fri, 11 May :26:46 GMT
Content: A bunch of HTML
Status: 200

12. Watching HTTP traffic Some browsers provide tools to view HTTP traffic
Great for understanding what your browser is doing
Tracking programmatic traffic requires a separate tool

13. HTTP Sniffers Macintosh: HTTPScoop http://tuffcode.com/
Macintosh: Charles (supports SSL)
Windows: Fiddler
Unix (or Mac): Wireshark (X11)

14. Example: HTTPScoop

15. Example: HTTPScoop
Request

16. Example: HTTPScoop
Headers

17. Example: HTTPScoop
Request/Response

18. REST APIs Leverage HTTP
Uses URL paths to define resources
Create, Read, Update, Delete
POST, GET, PUT, DELETE
Error Codes
HTTP Status Codes
Request parameters
Query parameters
Response types and configuration
Headers

19. Example REST Request Blog Info from Tumblr
GET (read)
Requires api_key sent as parameter

20. Example Request: Httpscoop

21. Example Request: Httpscoop
Headers

22. Example Request: Httpscoop
Request/Response

23. Example REST Response
Status: 200 Content: {"meta": {"status":200, "msg":"OK” }, "response":{ "blog":{"title":"Untitled","posts":0, "name":"synedra", "url":" "updated":0, "description":"","ask":false,"likes":0}}}

24. OAuth Authentication Used by many APIs
Each application gets a consumer key and secret
Authentication server handles authentication
Each user of an application gets a unique user token and secret
Supports tracking of application/member use of the API
Allows users to protect username/password
Industry standard – libraries for most programming languages

25. How does OAuth Work?
REST web services call adds verification signature to each request
Query parameters
Authorization header
Secrets are used to create signature
Authentication server checks signature to verify that it was created using shared secrets
If authentication succeeds, request is processed by API server

26. OAuth Example - Parameters
Signature is generated based on
URL
Parameters
Consumer key
User token

27. OAuth Example - Parameters
Request

28. OAuth Example - Parameters
Headers (nothing special)

29. OAuth Example - Parameters
Request/Response

30. OAuth Example - Header Signature is generated based on
URL
Parameters
Consumer key
User token
URL is unchanged:
Authorization header has oauth stuff: OAuth realm=" oauth_body_hash="JtgCKBurLIPLM4dXkn2E3lgrfI4%3D", oauth_nonce=" ", oauth_timestamp=" ", oauth_consumer_key=”***KEY***", oauth_signature_method="HMAC-SHA1", oauth_version="1.0", oauth_token=”***TOKEN***", oauth_signature="8iWVpIK3LhRbu8JPf2gzC1YxQy4%3D"

31. OAuth Example - Header
No authorization parameters

32. OAuth Example - Header
Authorization is in the header

33. OAuth Example - Header
Request/response works the same

34. Using OAuth with Python
Download the oauth2 package from github
No, it’s OAuth 1.0a, ignore the name
Quick walkthrough to understand process
(but this talk is not about OAuth)
import oauth2 as oauth
consumer_key = 'xxxxxxxxxxxxxx'
consumer_secret = 'xxxxxxxxxxxxxx’
consumer = oauth.Consumer(consumer_key, consumer_secret)
client = oauth.Client(consumer)

35. Get a request token
First step in OAuth: Get a request token for this authorization session
OAuth library handles signing the request
import oauth2 as oauth
consumer_key = 'xxxxxxxxxxxxxx'
consumer_secret = 'xxxxxxxxxxxxxx’
consumer = oauth.Consumer(consumer_key, consumer_secret)
client = oauth.Client(consumer)
resp, content = client.request(request_token_url, "POST")
request_token = dict(urlparse.parse_qsl(content))

36. Get a verifier
Second step: Send the user to the server to authorize your application
After the user authorizes your application, the server returns a verification code for you to use
print "Go to the following link in your browser:"
print "%s?oauth_token=%s" % (authorize_url, request_token['oauth_token'])
accepted = 'n'
while accepted.lower() == 'n':
accepted = raw_input('Have you authorized me? (y/n) ')
oauth_verifier = raw_input('What is the PIN? ’)

37. Get the access token
Third step: Use the verifier and the request token to get an access token
This is usually a long lived token
token = oauth.Token(request_token['oauth_token'],
request_token['oauth_token_secret'])
token.set_verifier(oauth_verifier)
client = oauth.Client(consumer, token)
resp, content = client.request(access_token_url, "POST")
access_token = dict(urlparse.parse_qsl(content))

38. Make a call Make an API call using the OAuth library
The library handles the signature generation
url =
consumer = oauth.Consumer(
key=”XXXXX",
secret=”XXXXX")
token = oauth.Token(
client = oauth.Client(consumer, token)
resp, content = client.request(url)

39. Debugging APIs
Use the documentation and resources provided by the platform team
Consoles, IODocs, OAuth signature checkers
Use existing, tested libraries
Code defensively

40. Common Errors 401 authentication errors (signatures, tokens)
403 authorization errors (throttles, permissions)
400 errors – parameters, headers
Library out of sync with API

41. Debugging Strategies
Try building the request using just the OAuth library
Find someone else’s code that works
HTTP Servers aren’t that smart

42. Summary HTTP: Hypertext Transfer Protocol
REST: REpresentational State Transfer
OAuth: Authentication