API Antipatterns

Everyone *knows* how to build an API. This document describes how to NOT build one.

Transcript

1. API Anti Patterns or, how to not f**k up your API
2. API Anti Patterns or, how to not f**k up your API
3. or, tips on how to annoy your API consumers
4. or, think you know REST? Awesome!
5. or, some of the crazy s**t people do with REST
6. Hello
7. Mike Pearce
8. http://social-network.com /MikePearce
9. http://social-network.com /MikeyPearce
10. http://social-network.com /mikepearce.net
11. http://social-network.com /MikePearce
12. An Apology
13. SONISPHERE @ Knebworth Flags should be banned a festivals!
14. Burritos: Best. Festival. Food. Ever.
16. Mike, Lee and Rog
17. SORRY
18. ( ) HTTP REQUEST: That you get on with it...
19. Why am I here? REST
20. Why am I here? REST
21. Why am I here? REST Hah!
22. Why am I here? REST Huh?! ST
23. Do’s ✔
24. Do’s Dont’s ✔ ✘
25. Do’s Dont’s Whatevs.. ✔ ✘ ☠
26. But first... Some background
27. Who? Roy Fielding (the grandfather)
28. There!
29. Architectural Styles and the Design of Network- based Software Architectures Can’t sleep? Read this...
31. A quick primer And now ...
32. REST != HTTP
33. REST != HTTP REST != The Web
34. REST
35. REST IS NOT
36. REST IS NOT HARD
37. REST IS NOT HARD Seriously!
38. Standards? We don’t need no steenkin’ standards!
39. MY CONSTRAINTS, LET ME SHOW YOU THEM
40. Some verbs...
41. Some nouns...
42. GET
43. PINT
44. PINT Please!
45. ANTI patterns Onto the main event
46. Overuse of ...
47. GET
49. Overuse of GET and POST or, GET/POST tunnelling.
52. BAD http://api.flickr.com/services/ rest/?method= flickr.photos.people.add &api_key=nnn&photo_id=yyy&u ser_id=xxx GET:
53. PUT: /user/MikePearce api_key=moo& age=33& size=medium& power=flight GOOD
54. PUT or POST? ASIDE PUT: /users/MikePearce PUT: /links/google PUT: /articles/100805/putorpost
55. PUT or POST? ASIDE POST: /documents/save name=styleguide.css& category=design
56. PUT or POST? ASIDE PUT when the resource will live at the target URI POST when you want the server to handle the location of the resource.
57. POST: /dostuff/ user=MikePearce& action=delete& api_key=moo& token=quack& mode=3 BAD
58. GOOD DELETE: /user/MikePearce Wait! What? Why!?
59. Tunneling Errors through 200 OK?
60. Are you OK? I’m fine! Great! A 200 OK!
61. I’m fine! Are you OK? ARGGHH! He doesn’t understand me! Great! A 200 OK!
62. This is better...
63. GET: /droid/r2d2 GET: /droid/c3po 404: Not the droids you’re looking for
64. HTTP/1.1 200 OK Content-Type: text/plain <?xml version="1.0" encoding="UTF-8" ?> <response code="error"> <error>Error!</error> <text>You have errored.</text> </response> What am I supposed to do with this?
65. RESPONSE CODES Which leads me nicely to...
66. IE has failed Informational
67. Success FTW!1
68. Redirection
69. Client Error (you try illustrating client error!)
70. Server Error It’s 1am. I can’t find an image for server error.
71. HTTP/1.1 200 OK PUT: /user/MikePearce Meh..
72. HTTP/1.1 201 CREATED PUT: /user/MikePearce Huzzah!
73. HTTP/1.1 418 GET: /whatareyou
74. HTTP/1.1 418 I’m a teapot GET: /whatareyou This one is real1!!
75. Caching
77. E-Tags
78. HTTP/1.1 304 NOT MODIFIED HTTP/1.1 200 OK Date: Mon, 23 May 2005 22:38:34 GMT Last-Modified: Wed, 08 Jan 2003 23:11:55 Etag: "3f80f-1b6-3e1cb03b" Connection: close Content-Type: text/html; charset=UTF-8
79. Mmm ... Delicious!
80. NO
81. HYPERMEDIA
82. HYPERMEDIA What is it?
83. HYPERMEDIA What is it?
84. HYPERMEDIA AS THE ENGINE OF APPLICATION STATE
85. oar...
86. HATEOAS (Remember hating oars)
87. Grey Areas
88. V3r510n1ng Versioning
89. GET: /user/MikePearce Him again. Prolific bastard.
90. GET: /user/MikePearce GET: /user/66
91. GET: /v1/user/MikePearce 1. Versioning with the URI GET: /v2/user/66
92. GET: /user/66 2. Not versioning the primary URI GET: /v1/user/MikePearce
93. GET: /user/66 3. No versioning
94. Document Extensions
95. Either
96. Either GET: /reports/tpsreport/summary.json GET: /reports/tpsreport/summary.xml
97. Either GET: /reports/tpsreport/summary.json GET: /reports/tpsreport/summary.xml or
98. Either GET: /reports/tpsreport/summary.json GET: /reports/tpsreport/summary.xml or Accept: text/xml Accept: application/json
99. SUM MARY Phew!
100. Overuse of GET and POST or, GET/POST tunnelling.
101. Tunneling Errors through 200 OK?
102. RESPONSE CODES Which leads me nicely to...
103. E-Tags
104. NO
105. HATEOAS (Remember hating oars)
106. V3r510n1ng Versioning
107. Either GET: /reports/tpsreport/summary.json GET: /reports/tpsreport/summary.xml or Accept: text/xml Accept: application/json
108. Any questions? (that I can answer!)
109. Photo Credits Wordle.net flickr.com/photos/wouterkiel/3717057757/ - Wouter Kiel flickr.com/photos/joe_13/19946186/ - joe_13 flickr.com/photos/23846880@N00/391925649/ - Rutger de Moddertukker flickr.com/photos/mararie/264942105/ - mararie flickr.com/photos/ndanger/7841795/ - ndanger flickr.com/photos/yourdon/2573762303/ - Ed Yourdon flickr.com/photos/thunderchild5/225675773/ - Thunderchild7 flickr.com/photos/duchamp/126115989/ - Duchamp flickr.com/photos/thefangmonster/490423135/ - The fang monster flickr.com/photos/nostri-imago/2894328425/ - cliff1066 flickr.com/photos/epsos/4582789354/ - epSos.de flickr.com/photos/projector/2092517108/ - allie pasquier flickr.com/photos/nickstone333/3135320160/ - nickstone333 flickr.com/photos/rdrcollection/116454033/ - Rodney Ramsey flickr.com/photos/christophercarfi/2730304130/ - Christophercarfi flickr.com/photos/turatti/4526352835/ - jaci xIII
110. Mike Pearce mike@mikepearce.net mikepearce.net twtitter.com/mikepearce Thanks!