Downloaded 392 times
Uploaded byMike Pearce
Api anti patterns
The document discusses several API anti-patterns including overuse of GET and POST methods, tunneling errors through responses, lack of proper response codes, absence of caching headers, hypermedia as the engine of application state (HATEOAS), versioning issues, and lack of content negotiation support. It provides examples of bad and good practices and concludes with reminding API designers to leverage standards to avoid confusing or annoying API consumers.
More Related Content
Api anti patterns
- 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 onhow to annoy your API consumers
- 4. or, think youknow REST? Awesome!
- 5. or, some ofthe crazy s**t people do with REST
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13. RE HE h ISP ort S ON ebw @ Kn Flags shoul d be banne d a festival s!
- 14. Bu rritos: l. Food . Ever. Best. Festiva
- 16.
- 17.
- 18. ( HTTP REQUEST: ) That you get on with it...
- 19.
- 20.
- 21. a mIh ere? Why REST Ha h!
- 22. a mIh ere? Why ST REST Hu h?!
- 23. Do’s ✔
- 24. Do’s ✔ Dont’s ✘
- 25. Do’s ✔ Dont’s ✘ Whatevs.. ☠
- 26. Some But first... background
- 27. Who? Roy Fielding (thegrandfather)
- 28.
- 29. Architectural Styles and the Design of Network- Can’t s ead tbased leep? his... Software R Architectures
- 31. A A nd now ... quick primer
- 32.
- 33. REST != HTTP REST!= The Web
- 34.
- 35.
- 36. REST IS NOT HA
- 37. REST IS NOT Se HA riou sly!
- 38. Standards? We don’t needno steenkin’ standards!
- 39. MY CONSTRAINTS, LET MESHOW YOU THEM
- 40.
- 41.
- 42.
- 43.
- 44.
- 45. main event Ont othe ANTI patterns
- 46.
- 47.
- 49. Overuse of GET andPOST or, GET/POST tunnelling.
- 52. GET: BA http://api.flickr.com/services/ rest/?method= flickr.photos.people.add &api_key=nnn&photo_id=yyy&u ser_id=xxx
- 53.
- 54. PUT or POST? PUT:/users/MikePearce PUT: /links/google PUT: /articles/100805/putorpost ASIDE
- 55. PUT or POST? POST:/documents/save name=styleguide.css& category=design ASIDE
- 56. PUT or POST? PUTwhen the resource will live at the target URI POST when you want the server to handle the location of the resource. ASIDE
- 57. POST: /dostuff/ user=MikePearce& BA action=delete& api_key=moo& token=quack& mode=3
- 58. DELETE: /user/MikePearce Wait! W hat? Wh y!? GOOD
- 59. Tunneling Errors through
- 60. Are you OK? I’m fine! Great! A 200 OK!
- 61. Are you OK? I’m fine! Great! A 200 OK! ARGGHH! He doesn’t understand me!
- 62.
- 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> ed t o do </response> I su ppos What am this? with
- 65. Which leads menicely to... RESPONSE CODES
- 66. IE has failed Informational
- 67. FTW!1 Success
- 68.
- 69. illust rating (yo utry ent er ror!) cli Client Error
- 70. n’t fi ndan s 1am . I ca error. It’ erver i mage for s Server Error
- 71.
- 72. PUT: /user/MikePearce HTTP/1.1 201CREATED Huzzah!
- 73.
- 74. GET: /whatareyou HTTP/1.1 418 I’ma teapot is real1!! This one
- 75.
- 77.
- 78. HTTP/1.1 304 NOT MODIFIED HTTP/1.1200 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.
- 80.
- 81.
- 82.
- 83.
- 84. HYPERMEDIA ASTHE ENGINE OF APPLICATION STATE
- 85.
- 86.
- 87.
- 88. V3r510n1ng Versioning
- 89. GET: /user/MikePearce in. Prolific Him aga bas tard.
- 90. GET: /user/MikePearce GET: /user/66
- 91. 1. Versioning withthe URI GET: /v1/user/MikePearce GET: /v2/user/66
- 92. 2. Not versioningthe primary URI GET: /user/66 GET: /v1/user/MikePearce
- 93. 3. No versioning GET:/user/66
- 94.
- 95.
- 96.
- 97.
- 98. Either GET: /reports/tpsreport/summary.json GET: /reports/tpsreport/summary.xml or Accept: text/xml Accept: application/json
- 99.
- 100. Overuse of GET andPOST or, GET/POST tunnelling.
- 101. Tunneling Errors through
- 102. Which leads menicely to... RESPONSE CODES
- 103.
- 104.
- 105.
- 106. V3r510n1ng Versioning
- 107. Either GET: /reports/tpsreport/summary.json GET: /reports/tpsreport/summary.xml or Accept: text/xml Accept: application/json
- 108. Any qu estions? swer!) (that I can an
- 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. Thanks! Mike Pearce mike@mikepearce.net mikepearce.net twtitter.com/mikepearce
Editor's Notes
- #3 Welcome to PHPLondon August 2010 meetup. I&#x2019;m here to talk about API Antipatterns and, more specifically, the use of REST.
- #4 or, some great ways to piss off your customers and users.
- #5 or, I&#x2019;m going to teach you to suck eggs.
- #6 or, we&#x2019;ll just laugh at other peoples&#x2019; expense.
- #7 So, hello, thanks for coming, you&#x2019;re all wonderful, really.
- #8 My name is Mike Pearce, this is my avatar, you&#x2019;ll see it liberally splashed about on various social networks.
- #9 You can usually find me as &#x2018;MikePearce&#x2019; on most networks.
- #10 or &#x2018;MikeyPearce&#x2019;
- #11 or even mikepearce.net
- #12 but, mostly MikePearce. I work for Affiliate Window, although I&#x2019;ve only been there two days, so don&#x2019;t ask me anything about them. Anyway, my contact details will be at the end if you&#x2019;re still awake, or even still here...
- #13 Firstly an apology. this presentation is ill written, probably badly researched and definately un-rehearsed. I only had a couple of weeks notice and most of that time was already taken up with things like working, eating sleeping and high-maintenance children.
- #14 I also went to a festival, Sonisphere at Knebworth
- #15 I ate too much
- #16 Drank too much
- #17 and everything I had ever learned about my job fell out of my head for four days. Monday arrived, then Tuesday and I still hadn&#x2019;t done it.
- #18 So, along with starting a new job, I&#x2019;ve spent the last 48hours glued to Keynote.
- #19 Anyway, I shall get on with it now.
- #20 You probably think I am here to talk about REST, right?
- #21 Well, I&#x2019;m not.
- #23 Actually, I am ... sort of. I&#x2019;m here to talk about how NOT to do rest, which is much easier!
- #26 The do&#x2019;s, the dont&#x2019;s and the whatevs of a REST API.
- #28 Roy Fielding is a 45 year old Californian who ...
- #29 Is one of the principle authors of the HTTP 1.1 RFC
- #30 He also wrote a dissertation in 2000 called &#x2018;Architectural Styles andthe Design of Network-based Software Architectures&#x2019; for a doctorate of philosophy. Hands up who has read this!
- #31 ... and chapter 5 had all the meaty stuff about REST.
- #33 Rest isn&#x2019;t HTTP ...
- #34 and REST isn&#x2019;t &#x2018;The Web&#x2019;. I&#x2019;ve heard REST summarised as Roy Fielding&#x2019;s way of describing the existing architecture of the web. While this is true, that&#x2019;s not all it is. REST principles can be applied with many other technologies.
- #35 REST isn&#x2019;t particularly hard to get right.
- #36 REST isn&#x2019;t particularly hard to get right.
- #37 REST isn&#x2019;t particularly hard to get right.
- #38 REST isn&#x2019;t particularly hard to get right.
- #39 There aren&#x2019;t really any standards.
- #40 Just a few constraints and a couple of guidelines. http://www.flickr.com/photos/joe_13/19946186/ joe_13
- #41 REST is really a set of verbs
- #42 which are applied to nouns. Here is a short example...
- #43 JON, can you
- #44 me a pint
- #46 So, let&#x2019;s get into the anti patterns.
- #47 So, the first antipattern and these aren&#x2019;t in any particular order is..
- #48 http://www.flickr.com/photos/23846880@N00/391925649/ Rutger de Moddertukker
- #50 Probably one of the most obvious, yet most abused pattern is to use GET or POST for everything. As I mentioned earlier, REST is about applying verbs to nouns. The nouns HTTP has are few, granted, but still distinct enough to each have their own jobs. CAN YOU NAME ALL THE HTTP NOUNS?
- #52 TRACE - Echoes back the received request, so that a client can see what (if any) changes or additions have been made by intermediate servers. OPTIONS - Returns the HTTP methods that the server supports for specified URL. CONNECT - Converts the request connection to a transparent TCP/IP tunnel, usually to facilitate SSL-encrypted communication (HTTPS) through an unencrypted HTTP proxy PATCH - Is used to apply partial modifications to a resource.[8]
- #53 An example of GET tunnelling. While this is clear enough what&#x2019;s it&#x2019;s doing, it&#x2019;s not adhering to a rest restraint, so, not really RESTful.
- #54 Good example of storing a document
- #55 PUT or POST is a question you&#x2019;ll often ask yourself and it&#x2019;s not always clear cut. Generally, you&#x2019;ll use a PUT when you saving a document at a certain location or in a collection
- #56 and POST when you want the application to decide where to save the document.
- #57 It&#x2019;s not clear cut though, so use your best judgements. Just remember that when you PUT a document at a location that it already exists at, you should PUT the entire original document, otherwise you should use UPDATE.
- #58 Here is an example of using POST to delete.
- #59 This is much better, it&#x2019;s semantically correct and shorter to boot!
- #60 Next up, tunnelling all errors through 200 OK. This is one of my biggest beefs and something that&#x2019;s caught me out as a consumer a couple of times now.
- #61 Anyone recognise this? When consuming the API of my wife, I ask her, &#x2018;Are you OK?&#x2019; and she response with &#x2018;Fine&#x201D; which, in my head, is a 200 ok. http://www.flickr.com/photos/yourdon/2573762303/ - Ed Yourdon
- #62 Or this? From my wifes point of view.
- #64 The error I&#x2019;m receiveing reflects the request I made. It&#x2019;s not 200 OK not the droids you&#x2019;re looking for. THAT would be confusing. http://www.flickr.com/photos/thunderchild5/225675773/
- #65 THIS is the most confusing and downright useless response I ever received from a Telco provider I worked with in my last job. A 200 OK code, with a plain text header and an XML body...
- #66 Which leads on nicely to response codes. There are many Response Codes that you can return which will provide the consumer with a much better idea of how to handle the body of the response. They fall broadly into five categories.
- #67 1** information codes eg: continue, switching protocols
- #68 2xx codes: 200 OK, 201 created, 202 accepted
- #69 3xx redirection: 303 moved, 304 not modified http://www.flickr.com/photos/duchamp/126115989/ - Duchamp
- #70 4xx codes: 404, 401 Unauthorised http://www.flickr.com/photos/thefangmonster/490423135/ - The fang monster
- #71 5xx codes. Really, the crux of the matter here is use response codes that are relevant to the response you are sending.
- #72 A 200 OK is an appropriate response for a successful PUT request, but to really be on the ball...
- #73 ... send a 201 created!
- #74 You can also make up your own codes, if the standard ones really don&#x2019;t cut it.
- #75 You can also make up your own codes.
- #76 One of the greatest benefits of using HTTP is caching. However, HTTP caching is complex and scary. You should use it where you can and encourage your clients to make use of ...
- #77 http://www.flickr.com/photos/epsos/4582789354/ - epSos.de
- #78 ETags
- #79 ETags are sent with the header and are a unique representation of that resource at that time. Collision-resistant has functions should be used to generate an etag, which is sent to the client. the client stores caches the etag along with the rest of the response, but the next time it makes a request to the URI, it sends an if-none-match header, which contains the original etag. The server will compare the two and, if nothing has changed, send a 304 (Can anyone tell me what a 304 is?) (Not Modified), otherwise, it will respond with the new data. More about caching is outside of the scope of this prez, talk to me afterwards if you want to know more (although, I don't know much more!).
- #80 Cookies, delicious right? http://www.flickr.com/photos/projector/2092517108/ By allie pasquier
- #81 Don't do it. If you have to, don't put server state data in them and don't authenticate with them. I have no idea yet how local storage will affect how I develop an API. http://www.flickr.com/photos/nickstone333/3135320160/ nickstone333
- #83 What is hypermedia?
- #84 What is hypermedia? Hypermedia is the sequel to Hypertext. Hypermedia includes audio, images, text and links. http://www.crystalxp.net/galerie/en.id.3751-bagg-a-png.htm
- #87 HATEOAS: You should be able to access your API from a single URI and be able to traverse the entire API by just knowing the one URI. If you forget this, you're not taking advantage of one of the core concepts of REST. Your API is now self-documenting and can never be out of date. For example, what a consumer does:&#xA0; GET: /users/MikePearce (assuming it's not cached) the API should return user information about me, but also information about how to modify me, how to delete me and links to other collections that have something to do with me. It should really also return a number of fixed URIs for adding collections. Or should it? That's one way of doing it, another way would be to publish one URI which lists all the features of the API and the URIs that you can access them with. Perhaps the endpoint as a start? Most clients will construct their own URIs, but mostly because they're never given any links to follow from the API in the first place! You can change this!
- #88 So, as always there are grey areas. The lack of any standards or an RFC for REST means that there's often areas of the discipline which, for some, offer the opportunity for wiggle room. The first of these, which you will see debated frequently (and there's some great discussions on Stack Overflow) is... http://www.flickr.com/photos/rdrcollection/116454033/ Rodney Ramsey
- #89 As with anything SAAS, your API will change over time and this means that some of your URIs may change. Now, the URI is the most prominent part of a RESTful API. It is something the users will use forever. It is a long term commitment to the user, so you have to get it right first time. However, there might be times when you absolutely have to change the way something works. For example, your initial design decision to make the URIs human readable means you might end up with a request like this:
- #90 But, you've now decided that you'd be better off requesting the user from their ID.
- #91 While less human readable, the margin for error is less. However, now all your consumers and clients are unable to query for both. You could program your API to look for strings AS WELL as integers, but it's going to get messy quickly. So, the best bet is to version. I'll explain a couple of methods for versioning, but you should decide what is best for you.
- #94 3. No versioning at all (but with a 'sunset' period) (This is more difficult if the clients consuming your API are paying for it, or don't move very quickly, hence this becomes business decision, not a technical one.
- #95 Another grey area, but this one only really has two choices. How does your client request particular document type? http://www.flickr.com/photos/turatti/4526352835/ jaci xIII
- #97 You either use the .extension style...
- #99 or send Accept headers with your request. You should bare in mind though that some servers WILL cache old accept headers or, in some instances, completely ignore your Accept headers. So it&#x2019;s probably safer to use .extensions
- #100 Summary.
- #101 Don&#x2019;t use get and post for everything. There ARE other verbs to apply to your nouns.
- #102 Use appropriate error codes. If it&#x2019;s an error, it&#x2019;s not 200 OK (unless you were expecting and error code and 200 OK IS an error...)
- #103 Use appropriate response codes. A 201 created or 202 accepted is preferable to a 200 OK after a mutation.
- #104 Be responsible with caching. Suppy clients with an expiry time for the data you suppy and also encourage them to use etags
- #105 Only use cookies if you really have to and make sure they contain stateless data. Prefer HTTP Auth over cookie auth if you can.
- #106 Hate Oars, or, remember to provide links to other relevant parts of the API with your response. You can also provide a directory of URIs at your end point if you like.
- #107 Versioning is totally up to you, there are a few options, it depends on you and your clients&#x2019; needs.
- #108 Use &#x201C;dot&#x201D; extensions or an Accept header, perhaps even both for those proxies which don&#x2019;t behave themselves.
- #109 Which leads on nicely to response codes. There are many Response Codes that you can return which will provide the consumer with a much better idea of how to handle the body of the response. They fall broadly into five categories.
- #111 My name is Mike Pearce, this is my avatar, you&#x2019;ll see it liberally splashed about on various social networks.