APIs - the good, the bad and the ugly

This session would describe what are the best practices of writing RESTful APIs. What are the different tools to create and test these APIs? What are the common pitfalls and how to avoid them? What are some of the industries best public APIs, etc. This session might also include a quick and easy hands-on session to fire and launch some APIs in the cloud using Play! Framework.

Transcript

1. HTTP/1.1! Server:! 200 OK! nginx! Date:"Wed, 14 Content-Type:! Sep 2014 14:03:33! application/json;! GMT! charset=utf-8! Connection: Status: 200! keep-alive OK! ETag:! "ef742caec0c19e2169ffb05e7d200d17"! Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT! {! }! "talk": apis – the good, the bad & the ugly,! "name” : nikhil bendre,! "twitter” : @npbendre,! “site”: npbendre.com!
2. API
3. REST as a Guide
4. HTTP/1.1! Server:! 200 OK! nginx! Date:"Wed, 14 Content-Type:! Sep 2014 14:03:33! application/json;! GMT! charset=utf-8! Connection: Status: 200! keep-alive OK! ETag:! "ef742caec0c19e2169ffb05e7d200d17"! Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT! ! {! }! GET https://api.example.com/user/8913   "talk": apis – the good, the bad & the ugly,! "name” : nikhil bendre,! "twitter” : @npbendre,! “site”: npbendre.com!
5. HTTP/1.1! Server:! 200 OK! nginx! Date:"Wed, 14 Content-Type:! Sep 2014 14:03:33! application/json;! GMT! charset=utf-8! Connection: Status: 200! keep-alive OK! ETag:! "ef742caec0c19e2169ffb05e7d200d17"! Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT! ! {! }! GET https://api.example.com/user/1234   "talk": apis – the good, the bad & the ugly,! "name” : nikhil bendre,! "twitter” : @npbendre,! “site”: npbendre.com!
6. HTTP/1.1! Server:! 200 OK! nginx! Date:"Wed, 14 Content-Type:! Sep 2014 14:03:33! application/json;! GMT! charset=utf-8! Connection: Status: 200! keep-alive OK! ETag:! "ef742caec0c19e2169ffb05e7d200d17"! Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT! ! {! }! GET https://api.example.com/user/1234   "talk": apis – the good, the bad & the ugly,! "name” : nikhil bendre,! "twitter” : @npbendre,! “site”: npbendre.com!
7. HTTP/1.1! Server:! 200 OK! nginx! Date:"Wed, 14 Content-Type:! Sep 2014 14:03:33! application/json;! GMT! charset=utf-8! Connection: Status: 200! keep-alive OK! ETag:! "ef742caec0c19e2169ffb05e7d200d17"! Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT! ! {! }! GET https://api.example.com/user/1234   "talk": apis – the good, the bad & the ugly,! "name” : nikhil bendre,! "twitter” : @npbendre,! “site”: npbendre.com!
8. HTTP/1.1! Server:! 200 OK! nginx! Date:"Wed, 14 Content-Type:! Sep 2014 14:03:33! application/json;! GMT! charset=utf-8! Connection: Status: 200! keep-alive OK! ETag:! "ef742caec0c19e2169ffb05e7d200d17"! Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT! ! {! }! GET https://api.example.com/user/1234   "talk": apis – the good, the bad & the ugly,! "name” : nikhil bendre,! "twitter” : @npbendre,! “site”: npbendre.com!
9. HTTP/1.1! Server:! 200 OK! nginx! Date:"Wed, 14 Content-Type:! Sep 2014 14:03:33! application/json;! GMT! charset=utf-8! Connection: Status: 200! keep-alive OK! ETag:! "ef742caec0c19e2169ffb05e7d200d17"! Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT! ! {! }! GET https://api.example.com/user/1234   "talk": apis – the good, the bad & the ugly,! "name” : nikhil bendre,! "twitter” : @npbendre,! “site”: npbendre.com!
10. api.example.com/me
11. http://maps.company.com/maps/api/ staticmap?center=Brooklyn+Bridge,New! +York,NY&zoom=13&size=600x300&maptype=road map&markers=color:blue%7Clabel:S! %7C40.702147,-74.015794&markers=color:gree n%7Clabel:G%7C40.711614,-74.012318! &markers=color:red%7Ccolor:red%7Clabel:C! %7C40.718217,-73.998284&sensor=false!
12. FIRST: DEFINE RESOURCES A Good Approach: Structure Y our URLs
13. what if /createUser /getDirectory /verifyUser /updateUser /createEvent
14. what if /createUser /getDirectory /verifyUser /updateUser /createEvent /verifyEvent /deleteUser /updateUser /updateUserName …………………….
15. collection & instance /files /files/982
16. SECOND: USE RESOURCES CRUD, but not really
17. Partially update a resource GET POST PUT DELETE PATCH Retrieve resource Create resource Update a resource Delete a resource HEAD Get only the headers
18. Media Type Request: Accept header Response: Content-Type header
19. Meaningful Response Code
21. 2xx: Success 3xx: Redirection 4xx: Client Error 5xx: Server Error
22. Bad {“error”: “code 782” } Good HTTP 1.1 400 { “error” : “field was missing”, “link” : “apidocs.com/400”, }   error response
23. Versioning
24. Accept Content-Type application/json+foo;application&v1 https:/ /api.example.com/v1 vs
25. ETAGS ARE COOL. NOBODY USES’EM
26. HTTP/1.1! Server:! 200 OK! nginx! Date:"Wed, 14 Content-Type:! Sep 2014 14:03:33! application/json;! GMT! charset=utf-8! Connection: Status: 200! keep-alive OK! ETag:! "ef742caec0c19e2169ffb05e7d200d17"! Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT! {! }! “data”: …! Server Response
27. HTTP/1.1! 304 Not Modified! Date:"Wed, 14! Sep 2014 14:03:33! GMT! Last-Modified: Sat, 13 Sep 2014 10:53:21 GMT! Client Request curl -i -H "If-None-Match: \"ef742caec0c19e2169ffb05e7d200d17\"" "https://graph.beta.facebook.com/me/ adaccounts?access_token=___"!
28. HYPERMEDIA
29. SUN CLOUD API GET /machines/1/ Host: example.com Accept: application/xml Sample Request
30. HTTP/1.1 200 OK Content-Type: application/xml <status>stopped</status> <link rel="start" method="post" href="machines/2?op=start" /> Sample Response
31. Security
32. Photo by Tojosan - Creative Commons Attribution-NonCommercial-ShareAlike License https://www.flickr.com/photos/28069288@N00   Created with Haiku Deck  
36. Models Proprietary Solution Basic Authentication OAuth 1.0 OAuth 2.0
37. Make Docs Obvious
39. Supported Options Examples Required & Optional Attributes Default Values Error Codes
40. Automate
44. Build something meaningful with your APIs
47. RATE LIMIT
48. Photo by GirlieMac - Creative Commons Attribution License https://www.flickr.com/photos/70561195@N00   Created with Haiku Deck  
49. CHATTY API
50. Let’s Play!
51. Download Play 2.3.4
52. Compile, Run & Test activator new select template & name activator run
54. Controllers GET / controllers.Application.index() GET /users ...getUsers() GET /users/:id ...getUserById(id: String) …
55. Models Ebeans for Java JPA Annotations Versioned Evolution Scripts
56. Test Based on JUnit Mockito Integration & UI Test
57. Pros Easy Url routing Class Reloading Java&Scala support Java/Ebean support NIO Server
58. TEST & PERFORMANCE
59. RUNSCOPE
60. Thanks
61. Attributions •  Cat by Marco Petrucci from The Noun Project •  Chat by Alberto Guerra Quintanilla from The Noun Project •  Coffee by Monika Ciapala from The Noun Project •  Key by Simple Icons from The Noun Project •  Lock by Jardson A. from The Noun Project •  Magnifying Glass by Naomi Atkinson from The Noun Project •  Gauge by Olivier Guin from The Noun Project •  Lock by Andrew Forrester from The Noun Project •  Fork by Dmitry Baranovskiy from The Noun Project •  Click icon is open source •  Document icon by Joe Richardson from The Noun Project •  Robot icon by Jon Trillana •  Tasks list by Arthur Shlain from The Noun Project •  Graph by David Waschbüsch from The Noun Project •  HTTP cats photo from girliemac •  Photo by Tojosan