Kirsten Jones, Technical Leader, Cisco Systems Demystifying REST
Who’s this talk for? Application Developers …Curious about using REST …Wanting help debugging the system Not REST API Architects (sorry!)
What Will I Cover? HTTP Overview REST Web Services OAuth Authentication Basics REST Debugging
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
How does HTTP Work? Client sends a request Method URL Headers (sometimes) parameters (sometimes) body Server replies with a response Content Status
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 to @DanaDanger for this
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
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
Parameters Part of the URL Everything after the question mark, delimited by ampersands http://www.example.com/search_people?this=that&foo=bar
An example request Chrome browser sends a request to Google Method: GET URL: http://www.google.com 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-8859-1,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/535.19 (KHTML, like Gecko) Chrome/18.0.1025.168 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=1336752507:LM=1336752509:S=W0Hha7x4czdXp51U Host: www.google.com
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-2012 21: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 2012 21:26:46 GMT Content: A bunch of HTML Status: 200
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
HTTP Sniffers Macintosh: HTTPScoop http://tuffcode.com/ Macintosh: Charles (supports SSL) http://www.charlesproxy.com/ Windows: Fiddler http://www.fiddler2.com/fiddler2/ Unix (or Mac): Wireshark (X11) http://www.wireshark.org/
Example: HTTPScoop
Example: HTTPScoop Request
Example: HTTPScoop Headers
Example: HTTPScoop Request/Response
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
Example REST Request Blog Info from Tumblr GET (read) http://api.tumblr.com/v2/blog/synedra.tumbler.com/info Requires api_key sent as parameter http://api.tumblr.com/v2/blog/synedra.tumblr.com/info?api_key=my_api_key
Example Request: Httpscoop
Example Request: Httpscoop Headers
Example Request: Httpscoop Request/Response
Example REST Response Status: 200 Content: {"meta": {"status":200, "msg":"OK” }, "response":{ "blog":{"title":"Untitled","posts":0, "name":"synedra", "url":"http:\/\/synedra.tumblr.com\/", "updated":0, "description":"","ask":false,"likes":0}}}
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
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
OAuth Example - Parameters Signature is generated based on URL Parameters Consumer key User token http://api.linkedin.com/v1/people/url=http%3A%2F%2Fwww.linkedin.com%2Fin%2Fsynedra?oauth_body_hash=2jmj7l5rSw0yVb%2FvlWAYkK%2FYBwk%3D&oauth_nonce=6283929&oauth_timestamp=1336775605&oauth_consumer_key=***KEY***&oauth_signature_method=HMAC-SHA1&oauth_version=1.0&oauth_token=***TOKEN***&oauth_signature=CqHiZI6tI3pQGe5a0vVgoT0822A%3D
OAuth Example - Parameters Request
OAuth Example - Parameters Headers (nothing special)
OAuth Example - Parameters Request/Response
OAuth Example - Header Signature is generated based on URL Parameters Consumer key User token URL is unchanged: http://api.linkedin.com/v1/people/~/shares Authorization header has oauth stuff: OAuth realm="http://api.linkedin.com", oauth_body_hash="JtgCKBurLIPLM4dXkn2E3lgrfI4%3D", oauth_nonce="60723468", oauth_timestamp="1336776657", oauth_consumer_key=”***KEY***", oauth_signature_method="HMAC-SHA1", oauth_version="1.0", oauth_token=”***TOKEN***", oauth_signature="8iWVpIK3LhRbu8JPf2gzC1YxQy4%3D"
OAuth Example - Header No authorization parameters
OAuth Example - Header Authorization is in the header
OAuth Example - Header Request/response works the same
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)
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))
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? ’)
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))
Make a call Make an API call using the OAuth library The library handles the signature generation url = http://api.linkedin.com/v1/people/~ consumer = oauth.Consumer( key=”XXXXX", secret=”XXXXX") token = oauth.Token( client = oauth.Client(consumer, token) resp, content = client.request(url)
Debugging APIs Use the documentation and resources provided by the platform team Consoles, IODocs, OAuth signature checkers Use existing, tested libraries Code defensively
Common Errors 401 authentication errors (signatures, tokens) 403 authorization errors (throttles, permissions) 400 errors – parameters, headers Library out of sync with API
Debugging Strategies Try building the request using just the OAuth library Find someone else’s code that works HTTP Servers aren’t that smart
Summary HTTP: Hypertext Transfer Protocol REST: REpresentational State Transfer OAuth: Authentication