Don't screw it up: how to build durable web apis @ PHPDay 2014 in Verona (ITA)

http://www.slideshare.net/odino/dont-screw-it-up-how-to-build-durable-web-apis-phpday-2014-in-verona-ita

Transcript

1. Don’t screw it up! @cirpo @_odino_
2. How to build durable web APIs
3. How to build durable web APIs 1. Can you predict the future?
4. Dubai Marina, ~2000
5. Dubai Marina, 2014
6. Can you really predict the future?
7. If there’s one thing we learned over the past 5 years of development...
8. Monoliths are disappearing
9. Full stack is dead Microservice Architecture, [...] a particular way of designing software applications as suites of independently deployable services http://martinfowler.com/articles/microservices.html “ ”
10. Full stack is dead Microservice Architecture, [...] a particular way of designing software applications as suites of independently deployable services http://martinfowler.com/articles/microservices.html “ ” SERVICE-ORIENTED ARCHITECTURES
11. LEGO, something new in a geek presentation...
13. FROM a single page application written in
14. TO an hybrid solution
15. In TWO weeks!
16. HOW???
17. APIs written in PHP <3
18. Everyone wants APIs
19. Everyday normal services
20. dev-oriented services
21. API maniacs
22. 2. HTTP is here to stay
23. GET vs POST “The difference is that in a GET request you have the parameters in the url , with a POST the parameters are in the request’s body”
24. GET vs POST
25. HTTP FUNDAMENTALS
26. HTTP FUNDAMENTALS GET POST
27. HTTP FUNDAMENTALS GET POST PUT HEAD DELETE PATCH OPTIONS
28. HTTP FUNDAMENTALS HEADERS Accept Accept-Encoding Accept-Language Cookie Content-Type Referer If-Modified-Since If-None-Match Origin User-Agent Cache-Control
30. HTTP FUNDAMENTALS CUSTOM HEADERS N-Location N-Locale N-Device N-Platform N-App N-Theme
31. WAKA “A new protocol designed to match the efficiency of well-designed Web Applications” http://tools.ietf.org/agenda/83/slides/slides-83-httpbis-5.pdf
32. SPDY/1..3 A protocol “invented” by Google, which supports: extended compression multiplexing prioritization server push
33. SPDY/1..3 A protocol “invented” by Google, which supports: extended compression multiplexing prioritization server push
34. SPDY/1..3 A protocol “invented” by Google, which supports: extended compression multiplexing prioritization server push
35. SPDY/1..3 A protocol “invented” by Google, which supports: extended compression multiplexing prioritization server push
36. SPDY/1..3 A protocol “invented” by Google, which supports: extended compression multiplexing prioritization server push
37. HTTP/2.0
38. HTTP/2.0 based on SPDY
39. HTTP/2.0 which is a faster version of HTTPS
40. HTTP/2.0 which is a safer version of HTTP
41. HTTP is definitely here to stay, semantics won’t change
42. 3. Plan for failure
43. Work around bugs https://gist.github.com/odino/11295759/revisions
44. Work around bugs https://gist.github.com/odino/11295759/revisions
45. Failover HTTP/1.1 200 OK Date: Fri, 25 Apr 2014 16:52:37 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Vary: Accept-Encoding Cache-Control: stale-if-error=3600, stale-while-revalidate=6000 Age: 0 Via: 1.1 varnish X-Cache: MISS Alternate-Protocol: 443:npn-spdy/2
46. Failover HTTP/1.1 200 OK Date: Fri, 25 Apr 2014 16:52:37 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Vary: Accept-Encoding Cache-Control: stale-if-error=3600, stale-while-revalidate=6000 Age: 0 Via: 1.1 varnish X-Cache: MISS Alternate-Protocol: 443:npn-spdy/2
47. Failover HTTP/1.1 200 OK Date: Fri, 25 Apr 2014 16:52:37 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Vary: Accept-Encoding Vary: Accept-Encoding Cache-Control: stale-if-error=3600, stale-while-revalidate=6000 Age: 0 Via: 1.1 varnish X-Cache: MISS alternate-protocol: : 443:npn-spdy/2 Alternate-Protocol: 443:npn-spdy/2 cache available if the backend is down
48. Design mistakes?
49. Versioning to the rescue
50. Versioning to the rescue https://gist.github.com/odino/bf4c7468cba8b16c6493
51. Versioning to the rescue https://gist.github.com/odino/f820dda941bf44aa7605
52. Versioning to the rescue https://gist.github.com/odino/b5d963d8f8aec904d76c
53. Versioning to the rescue https://gist.github.com/odino/0fbb5be8113deed752fc
54. How to detect the version?
55. How to detect the version? api.domain.org/v1/...
56. How to detect the version? SIMPLE
57. How to detect the version? ...but how to detect it?
58. Detecting the version https://gist.github.com/odino/f5a1026449e35cfa8a29
59. Detecting the version https://gist.github.com/odino/f5a1026449e35cfa8a29 Here it belongs to the route/controller, you need it at the Request level
60. Detecting the version https://gist.github.com/odino/f5a1026449e35cfa8a29 Use a header!
61. Detecting the version https://gist.github.com/odino/bf4c7468cba8b16c6493
62. Can’t test it easily!
63. Let Nginx do the dirty work https://gist.github.com/odino/6750004f735c8d08687d
64. Let Nginx do the dirty work https://gist.github.com/odino/6750004f735c8d08687d example.org/v1/customers/1
65. Let Nginx do the dirty work https://gist.github.com/odino/6750004f735c8d08687d example.org/customers/1 Api-Version: 1
66. Let Nginx do the dirty work https://gist.github.com/odino/6750004f735c8d08687d $req->getHeader(‘Api-Version’)
67. Let Nginx do the dirty work https://gist.github.com/odino/6750004f735c8d08687d Without polluting routing and controllers
68. “I beg to differ”
69. “I beg to differ” URL, subdomain, media type, header...
70. “I beg to differ” Picking a wrong implementation doesn’t matter
71. “I beg to differ” Picking a wrong implementation doesn’t matter AT ALL.
72. “I beg to differ” How it impacts the design of your software matters
73. “I beg to differ” #NoSilverBullet
74. 4. Be Pragmatic
75. /login GET or POST?
76. 5. Testing
77. cURL is your best friend curl -X GET https://api.namshi.com/products curl -X POST https://api.namshi.com/order -data=”{...}” curl -X DELETE ... curl -X PATCH ...
78. cURL is your best friend
79. cURL is your best friend
80. cURL is your best friend
81. cURL is your best friend https://docs.python.org/2/library/json.html
82. httparty https://docs.python.org/2/library/json.html
83. httpie https://github.com/jkbr/httpie
84. smoke tests made easy
85. consuming/testing apis locally https://gist.github.com/cirpo/92fa22d4c45fddf0ccfa
86. consuming/testing apis locally https://gist.github.com/cirpo/c6d497c5654094904306
87. testing apis
88. Android 2.3 native browser
89. testing apis
90. testing apis you can even decrypt the https responses :)
91. 6. Design
92. An API is a layer on top of your domain
93. Pick the layer that is most suitable to your needs
94. HTTP APIs are a good start
95. REST is a DREAM
96. POST or PUT? HTTP METHOD
97. PUT or PATCH? HTTP METHOD
98. /users/johnny/tags USER TAGS
99. USER TAGS to remove a tag PUT, PATCH or DELETE?
100. USER TAGS deleting a non-existent tag 200 or 204 or 404? http://stackoverflow. com/questions/2342579/http-status-code- for-update-and-delete
101. USER TAGS deleting a non-existent tag 200 or 204 or 404? http://stackoverflow. com/questions/2342579/http-status-code- for-update-and-delete ON STACKOVERFLOW THEY’RE STILL FIGHTING http://stackoverflow.com/questions/2342579/http-status-code-for-update-and-delete
102. be consistent
103. NAMING /user/1 /users /order/1 /orders
104. NAMING /city/1 /cities /curriculum/1 /curricula
105. NAMING /user/1 /users /order/1 /orders /city/1 /cities /curriculum/1 /curricula
106. NAMING /user/1 /users /order/1 /orders /city/1 /cities /curriculum/1 /curricula not good AT ALL!
107. STICK WITH PLURALS
108. NAMING /users/1 /users /orders/1 /orders /cities/1 /cities /curricula/1 /curricula
109. UNIQUE RESOURCES /users/1 /users/cirpo /users/A323K833
110. UNIQUE RESOURCES /orders/15 /orders/A323K833
111. UNIQUE RESOURCES AVOID INCREMENTAL NUMBER (if it’s business critical)
112. Unstructured APIs = API aggregation
113. api.example.org/v1/latest-news
114. latest news + metatags + banners + navigation yada yada yada
115. Sort of a “wild” API for your whole app
116. The client receives a GET on /something and will let the API figure out what /u/something actually is
117. Orchestration Layers
118. https://engineering.groupon.com/2013/misc/i-tier-dismantling-the-monoliths/
119. “Most APIs are designed by the API provider with the goal of maintaining data model purity. When building an OL, be prepared to sometimes abandon purity in favor of optimizations and/or performance.” Daniel Jacobson, director of engineering for the Netflix API http://www.infoq.com/presentations/API-Revolution
120. DOMAIN users orders stock images
121. DOMAIN Think about collections not controllers
122. DOMAIN PUT/PATCH try to always plan for full updates
123. uniform responses
124. codebase organization
125. codebase organization one bundle for each api? one bundle for each application? one app for each sets of api?
126. codebase organization start with an app organize bundles semantically create shared bundles
128. codebase organization BUNDLES product checkout warehouse generic entity
129. 7. Scalability
130. CACHE ALL THE THINGS!
131. Middlewares to the rescue!
132. CONNECT https://gist.github.com/cirpo/e9ec20871e2e8d433f8d
133. STACK https://gist.github.com/cirpo/11296317
134. STACK https://gist.github.com/odino/b3fdacceaa0cce65fbce
135. Avoid sessions
136. Everything as a resource http://leaphly.org/
137. 8. We have a problem
138. CORS
139. CORS
140. iFrames to the rescue!
141. iFrames to the rescue! domain.org includes an iframe from api.domain.org
142. iFrames to the rescue! then sends it a message through the postMessage API
143. iFrames to the rescue! the iFrame triggers the ajax request on its own domain with the parameters in the message
144. iFrames to the rescue! and sends the result back to the caller
145. iFrames to the rescue! and sends the result back to the caller #ghetto
146. CORS xDomain, cross-browser without CORS https://github.com/jpillora/xdomain
147. CORS great idea, but Jaime is alone :(
148. CORS poor file upload support
149. CORS no automated tests
150. CORS not a long-term solution :’-(
151. CORS xAuth, a standard https://github.com/xauth/xauth
152. CORS initially thought to provide a decentralized auth service
153. CORS on the centralized xauth.org http://hueniverse.com/2010/06/05/xauth-a-terrible-horrible-no-good-very-bad-idea/
154. CORS Dead.
155. CORS DEAD.
156. CORS Use an API proxy
157. CORS example.org/api/
158. (silly) browsers
159. (silly) browsers if a cross-domain request is cacheable, the android browser goes nuts
160. (silly) browsers The request does not include the Origin header
161. (silly) browsers Status code: 0
162. (silly) browsers WHAT. THE. HECK. http://opensourcehacker.com/2011/03/20/android-webkit-xhr-status-code-0-and-expires- headers/
163. “Standards”
164. Don’t play with fire
165. Don’t play with fire 1 API, N clients consuming it
166. Don’t play with fire desktop browser, mobile browser, ios app, android app...
167. Don’t play with fire Keep as much logic as possible on the server
168. Don’t play with fire Less things to implement on every client and centralized implementations
169. Don’t play with fire make it easy for the API clients
170. Don’t play with fire POST https://api.example.com/login 200 OK date: Thu, 01 May 2014 21:52:33 GMT content-type: application/json transfer-encoding: chunked connection: close set-cookie: login=...; cache-control: no-cache { "email"=>"alessandro.nadalin@gmail.com", "firstName"=>"Alex", "lastName"=>"Nadalin", "birthday"=>"21/10/1988", }
171. Security matters
172. Security matters [ "odino@gmail.com", "cirpo@gmail.com", ... ]
173. Security matters for(;;);[ "odino@gmail.com", "cirpo@gmail.com", ... ]
174. Security matters while(1);[ "odino@gmail.com", "cirpo@gmail.com", ... ]
175. Security matters while(1);[ "odino@gmail.com", "cirpo@gmail.com", ... ] http://bit.ly/why-does-google
176. Security matters Avoid [...] http://bit.ly/json-hijacking
177. Security matters Use {...}
178. That’s all folks
179. github.com/cirpo twitter.com/cirpo cirpo.org github.com/odino twitter.com/_odino_ odino.org Namshi Lead Developer Namshi VP Technology
180. github.com/cirpo cirpo.org thank you! joind.in/11310
181. we are hiring! tech.namshi.com/join-us github.com/namshi twitter.com/TechNamshi tech.namshi.com
183. CREDITS http://www.panoramio.com/photo/30329016 https://farm3.staticflickr.com/2199/2365883747_3a5c753719_o.jpg http://news.buzzbuzzhome.com/2013/04/top-7-aerial-photos-cities.html https://www.flickr.com/photos/superlekker/5917559189/sizes/l https://www.flickr.com/photos/derekbruff/12336187505/sizes/l https://www.flickr.com/photos/chberge/3803475294/sizes/l https://www.flickr.com/photos/neilsingapore/8057578769 https://www.flickr.com/photos/dionnehartnett/6805481856/sizes/l https://www.flickr.com/photos/thomashawk/186339737 https://www.flickr.com/photos/cesarastudillo/3981364314/sizes/l https://www.flickr.com/photos/an_untrained_eye/6630719431 https://www.flickr.com/photos/30835738@N03/7936491790/sizes/l https://www.flickr.com/photos/deboni/2959228565/sizes/l https://www.flickr.com/photos/ghalog/6782751111/sizes/l https://www.flickr.com/photos/timzim/177640262/sizes/o/ https://www.flickr.com/photos/innoxiuss/2824204305 https://www.flickr.com/photos/hawk59/6038847752/sizes/l https://www.flickr.com/photos/remydwd/5487417702/sizes/l https://www.flickr.com/photos/rammorrison/4359793666/sizes/o/ https://www.flickr.com/photos/piers_nye/2501994750/sizes/o/ https://www.flickr.com/photos/danielygo/7559750132/sizes/l https://www.flickr.com/photos/msc72/2600035028/sizes/l https://www.flickr.com/photos/sicilianitaliano/3609275241/sizes/l https://www.flickr.com/photos/scottmontreal/7235110028/sizes/l https://www.flickr.com/photos/piet_musterd/6170853224/sizes/l https://www.flickr.com/photos/music_embassy/7137413247/sizes/l http://upload.wikimedia.org/wikipedia/commons/9/9c/William_James_b1842c.jpg http://theverybesttop10.files.wordpress.com/2013/08/the-world_s-top-10-things-no-person-with-a-ocd-should-see-1. jpg https://www.flickr.com/photos/62244271@N03/8553590682/sizes/l