designing beautiful rest apis

Download Designing beautiful REST APIs

Post on 13-Jan-2015

2.285 views

Category:

Technology

1 download

Embed Size (px)

DESCRIPTION

Presented on 4Developers 2013 (12th April).

TRANSCRIPT

  • 1. DESIGNING BEAUTIFUL REST APIs@tomekcejner

2. THE PRESENTER 3. THE PRESENTER TOMEK CEJNER@tomekcejner www.japko.nettomek@japko.net 4. THE PRESENTER TOMEK CEJNER@tomekcejner www.japko.nettomek@japko.net 5. FASHION 6. WHAT REST MEANS 7. NO FRAMEWORKS 8. APPLICATIONS 9. APPLICATIONS GOING OPEN 10. APPLICATIONS GOING OPENGOING BIG 11. SOA 12. LOOSE COUPLING 13. LOOSE COUPLINGSMALLER CODEBASE 14. LOOSE COUPLINGSMALLER CODEBASE REUSABILITY 15. WEB SERVICES 16. WORLDS BIGGEST APP EVER 17. WORLD WIDE WEB 18. WHAT IS REST? 19. A PROTOCOL? 20. A PROTOCOL?NO 21. A SPECIFICATION? 22. A SPECIFICATION? NO 23. ARCHITECTURAL STYLE 24. ROY T. FIELDINGPHD DISSERTATION 25. http://www.w3.org/Protocols/rfc2616/rfc2616.html 26. BUILDING ARCHITECTURE 27. BUILDING ARCHITECTUREFROM SCRATCH 28. BUILDING ARCHITECTUREFROM SCRATCH FROM WHOLE 29. CONSTRAINTS 30. CONSTRAINTSCLIENT-SERVER 31. CONSTRAINTSCLIENT-SERVERSTATELESS 32. CONSTRAINTSCLIENT-SERVERSTATELESSCACHEABLE 33. CONSTRAINTSCLIENT-SERVERSTATELESSCACHEABLEUNIFORM INTERFACE 34. RESOURCE 35. URIhttp://www.example.com/blogs/423/entries/12340http://www.example.com/sales/2004/Q4http://www.example.com/bugs/by-state/open 36. URIhttp://api.example.com/places/42.089199,93.076172http://api.example.com/color-blends/yellow;blue 37. URIhttp://api.example.com/items?price_min=0&price_max=599 38. URIhttp://api.example.com/auctions/239841/cancel 39. URIhttp://api.example.com/auctions/239841/cancel 40. RICHARDSON MATURITY MODEL http://www.crummy.com/writing/speaking/2008-QCon/act3.html 41. LEVEL 0 42. LEVEL 0 HELL 43. POST /auctionServiceAPIEndpoint HTTP/1.1Macbook Air01000 44. HTTP/1.1 200 OK123Macbook Air499NEW 45. LEVEL 1 46. LEVEL 1URI 47. POST /auctions/1234/read 48. POST /auctions/1234/readGET /auctions/1234/read 49. POST /auctions/1234/readGET /auctions/1234/readPOST /auctions/create 50. POST /auctions/1234/readGET /auctions/1234/readPOST /auctions/createPOST /auctions/1234/update 51. LEVEL 2 HTTP 52. /auctions 53. /auctions/auctions/1234 54. GET 55. GETPOST 56. GETPOSTPUT 57. GET POST PUTDELETE 58. GET POSTPUTDELETE HEAD 59. GETPOST PUT DELETEHEADOPTIONS 60. GETPOST PUT DELETEHEADOPTIONS PATCH 61. GET 62. GET /auctions 63. GET /auctionsGET /auctions/1234 64. GET /auctionsGET /auctions/1234GET /auctions?search=Macbook+Air 65. SAFE + IDEMPOTENT 66. TESLA MODEL SIT HAS A RESTFUL API 67. GET http://api.flickr.com/services/rest?method=flickr.photos.people.add&api_key=xxx&photo_id=yyy&user_id=zzz 68. DELETE 69. DELETEDELETE /auctions/1234 70. DELETEDELETE /auctions/1234HTTP/1.1 204 No Content 71. DONT DO THIS AT HOME 72. DELETE 73. DELETEIDEMPOTENT 74. DELETEIDEMPOTENTNOT SAFE 75. POST 76. POST /items{! "name" : "Macbook Air 2010",! "condition" : "NEW",! "price" : 499} 77. POST /items{! "name" : "Macbook Air 2010",! "condition" : "NEW",! "price" : 499}201 CreatedLocation: http://api.alledrogo.com/items/1235 78. POST 79. POSTNOT IDEMPOTENT 80. POSTNOT IDEMPOTENT NOT SAFE 81. PUT 82. PUT /items/1235{"name" : "Macbook Air 2010",! "condition" : "LIKE_NEW",! "price" : 498} 83. PUT /users/joe{first_name : Joe,last_name : Smith} 84. PUTIDEMPOTENTNOT SAFE 85. POST: ID FROM SERVER 86. POST: ID FROM SERVER PUT: ID FROM CLIENT 87. OPTIONS 88. OPTIONSDISCOVERY 89. OPTIONS /users HTTP/1.1...HTTP/1.1 204 No ContentAllow: GET, POST, PUT 90. /users/users/456 GETGET ALLGET USERPOST CREATE NEW- PUT -UPDATEDELETE DELETE ALL DELETE USER 91. HTTP STATUS CODES 92. SUCCESS 93. SUCCESS200 OK 94. SUCCESS200 OK201 CREATED 95. SUCCESS200 OK201 CREATED202 ACCEPTED 96. SUCCESS200 OK201 CREATED202 ACCEPTED204 NO CONTENT 97. 201 CREATEDPOST /items/1234/bids{! "amount" : 602.99}201 CreatedLocation: http://api.alledrogo.com/items/1234/bids/100001{! "cap_amount" : 602.99,! "current_bid" : 510,! "winning" : true} 98. REDIRECT 99. REDIRECT301 MOVED PERMANENTLY 100. REDIRECT301 MOVED PERMANENTLY303 SEE OTHER 101. REDIRECT301 MOVED PERMANENTLY303 SEE OTHER304 NOT MODIFIED 102. REDIRECT301 MOVED PERMANENTLY303 SEE OTHER304 NOT MODIFIED307 TEMPORARY REDIRECT 103. USER ERROR 104. USER ERROR400 BAD REQUEST 105. USER ERROR400 BAD REQUEST401 UNAUTHORIZED 106. USER ERROR400 BAD REQUEST401 UNAUTHORIZED403 FORBIDDEN 107. http://cropp.com/404 108. 405 METHOD NOT ALLOWED 109. 409 CONFLICT 110. 410 GONE 111. SERVER ERROR 112. SERVER ERROR500 INTERNAL SERVER ERROR 113. SERVER ERROR500 INTERNAL SERVER ERROR503 SERVICE UNAVAILABLE 114. DONT IGNORE HTTP STATUS 115. DONT IGNORE HTTP STATUShttp://api.flickr.com/services/rest?method=flickr.photos.people.add&api_key=xxx&photo_id=yyy&user_id=zzz 116. DONT IGNORE HTTP STATUShttp://api.flickr.com/services/rest?method=flickr.photos.people.add&api_key=xxx&photo_id=yyy&user_id=zzzHTTP/200 OK 117. DONT IGNORE HTTP STATUShttp://api.flickr.com/services/rest?method=flickr.photos.people.add&api_key=xxx&photo_id=yyy&user_id=zzzHTTP/200 OK 118. LEVEL 3 119. LEVEL 3HYPERMEDIA 120. LINKING 121. SELF DESCRIBEDCAPABILITIESINTERCONNECTION 122. PRESENTATION XHTML XMLATOM... 123. NO HYPERMEDIAGET /items?q=macbook+air+new{! "results" : [! ! {! ! ! "id" : 1234,! ! ! "name" : "Macbook Air 2010 LIKE NEW",! ! ! "price" : "499"! ! }! ]} 124. WITH HYPERMEDIAGET /items?q=macbook+air+new{! "results" : [! ! {! ! ! "_links" : [! ! ! !{ "rel" : "self", "uri" : "/items/1234" },! ! ! !{ "rel" : "bids", "uri" : "/items/1234/bids" },! ! ! !{ "rel" : "highest_bid", "uri" : "/items/1234/bids?q=winning" }! ! ! ],! ! ! "name" : "Macbook Air 2010 LIKE NEW",! ! ! "price" : "499"! ! }! ]} 125. GET /items/1234{! "_links" : [! ! { "rel" : "self", "uri" : "/items/1234" },! ! { "rel" : "bids", "uri" : "/items/1234/bids"},! ! { "rel" : "seller", "uri" : "/users/9876"}! ],! "name" : "Macbook Air 2010 LIKE NEW",! "price" : "499"} 126. GET /users/9876{! "_links" : [! ! { "rel" : "self", "uri" : "/users/9876" },! ! { "rel" : "ratings", "uri" : "/users/9876/ratings" }! ! { "rel" : "messages", "uri" : "/users/9876/messages" }! ! { "rel" : "listings", "uri" : "/users/9876/listings" }! ],! "name" : "John Doe"} 127. POST /items/1234/bids{! "amount" : 602.99} 128. POST /items/1234/bids{! "amount" : 602.99}201 CreatedLocation: http://api.alledrogo.com/items/1234/bids/100001{! "_links" : [! ! { "rel" : "self", "uri" : "/items/1234/bids/100001" },! ! { "rel" : "item", "uri" : "/items/1234" },! ]! "cap_amount" : 602.99,! "current_bid" : 510,! "winning" : true} 129. DOMAIN APPLICATION PROTOCOL 130. HATEOAS 131. HATEOASHYPERMEDIA 132. HATEOASHYPERMEDIAAS 133. HATEOASHYPERMEDIAASTHE ENGINE 134. HATEOASHYPERMEDIA AS THE ENGINEOF APPLICATION STATE 135. IN PRACTICE 136. AUCTION SERVICE - USERS 137. AUCTION SERVICE - USERSdoGetMyDatadoGetUserIDdoGetUserItemsdoShowUserdoShowUserPage 138. AUCTION SERVICE - USERSdoGetMyDataGET /users/medoGetUserIDGET /users?name=czesiodoGetUserItems GET /users/123456/itemsdoShowUser GET /users/123456/detailsdoShowUserPage GET /users/123456/aboutpage 139. AUCTION SERVICE - MY AUCTIONS 140. AUCTION SERVICE - MY AUCTIONSdoGetFavouriteCategoriesdoGetFavouriteSellersdoGetMyBidItemsdoGetMyWatchItemsdoGetMySoldItemsdoRemoveFromWatchList 141. AUCTION SERVICE - MY AUCTIONSdoGetFavouriteCategories GET /users/me/favorites/categorydoGetFavouriteSellersGET /users/me/favorites/sellersdoGetMyBidItemsGET /users/me/bidsdoGetMyWatchItemsGET /users/me/items/watchingdoGetMySoldItems GET /users/me/items/solddoRemoveFromWatchListDELETE /users/me/items/watching/1 142. AUCTION SERVICE - BIDDING 143. AUCTION SERVICE - BIDDINGdoBidItemdoRequestCancelBid 144. AUCTION SERVICE - BIDDINGdoBidItem POST /items/54321/bidsdoRequestCancelBidDELETE /items/54321/bids/678 145. BEYOND CRUD 146. COPYGET /items/5001HTTP/1.1 200 OK{_links : [ { rel : self,href : /items/5001 }, { rel : duplicate,href : /items/5001/duplicate;t=37489231614874 }],name : MacBook Air,price : 599} 147. COPYPOST /items/5001/duplicate;t=37489231614874HTTP/1.1 201 CreatedLocation: /items/5002 148. SNAPSHOTPUT /items/5002{name : MacBook Air,price : 399}HTTP/1.1 204 No Content 149. SNAPSHOTGET /items/5002{_links : [{ rel : self, href : /items/5002},{ rel : duplicate, href : /items/5002/duplicate;t=98435943498},{ rel : previous, href : /items/5002/s1},{ rel : undo, href : /items/5002/undo;t=92312093},],name : MacBook Air,price : 599} 150. UNDOPOST /items/5002/undo;t=92312093HTTP/1.1 303 See OtherLocation: /items/5002 151. ASYNCHRONOUS OPERATION 152. ASYNCHRONOUS OPERATIONPOST /projects/123/tasks{ type : REPORT, date_from : 20130101, date_to : 20130331} 153. ASYNCHRONOUS OPERATIONPOST /projects/123/tasks{ type : REPORT, date_from : 20130101, date_to : 20130331}HTTP/1.1 202 Accepted{ state : PENDING, ping-after : 2013-04-12T17:02:32Z _links : [{ rel : outcome,href : http://api.example.com/reports/882 }, ]} 154. MEDIA TYPES 155. MEDIA TYPESContent-Type: application/vnd.alledrogo+xml 156. MEDIA TYPESContent-Type: application/vnd.alledrogo+xmlContent-Type: text/html 157. REST VS SOAP/RPC 158. REST VS SOAP/RPCCOMPLEMENT, NOT CONCURRENT 159. NATURE OF THE WEB 160. CALL IT REST 161. CALL IT RESTWHEN DOING IT REST 162. THANK YOU!