This is a talk I gave at IPC 2014 in Munich. It's about how to build durable web apis based on the experience gained at Namshi while we were developing our SOA architecture

1. Alessandro Cinelli (cirpo)
Don’t screw it up!
how to build durable apis

2. How to build
durable
web APIs

3. 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!
SERVICE-ORIENTED
ARCHITECTURES
Microservice Architecture, [...] a
particular way of designing software
applications as suites of independently
deployable services
http://martinfowler.com/articles/microservices.html

11. LEGO, something new in a geek talk…

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 API

19. EVERYDAY 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
PATCH DELETE
GET POST
PUT HEAD
OPTIONS

28. HTTP FUNDAMENTALS
HEADERS

29. HTTP FUNDAMENTALS
Cache-Control
Cookie Accept-Language
User-Agent Origin
HEADERS
Accept
Accept-Encoding
Content-Type
Referer
If-Modified-Since
If-None-Match

31. HTTP FUNDAMENTALS
CUSTOM HEADERS

32. HTTP FUNDAMENTALS
CUSTOM HEADERS
N-Location
N-Locale
N-Device
N-Platform
N-App
N-Theme

33. 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

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. SPDY/1…3
A protocol “invented” by Google, which supports:
extended compression
multiplexing
prioritization
server push

38. HTTP/2.0

39. HTTP/2.0
BASED ON SPDY

40. HTTP/2.0
WHICH IS A FASTER VERSION OF HTTPS

41. HTTP/2.0
WHICH IS A SAFER VERSION OF HTTP

42. HTTP is definitely here to stay,
semantics won’t change

43. 3. PLAN FOR
FAILURE

44. WORK AROUND BUGS

45. WORK AROUND BUGS

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
Cache-Control: stale-if-error=3600, stale-while-revalidate=6000
Age: CACHE 0
AVAILABLE IF BACKEND IS DOWN
Via: 1.1 varnish
X-Cache: MISS
Alternate-Protocol: 443:npn-spdy/2

48. DESIGN MISTAKES?

49. VERSIONING TO THE RESCUE

50. VERSIONING TO THE RESCUE

51. VERSIONING TO THE RESCUE

52. VERSIONING TO THE RESCUE

53. How to detect the version?

54. http://api.example.com/v1/…
How to detect the version?

55. SIMPLE
How to detect the version?

56. BUT HOW TO DETECT IT?
How to detect the version?

57. DETECTING THE VERSION

58. DETECTING THE VERSION
Here it belongs to
the route/controller, you need
it at the
Request level

59. USE A HEADER!
How to detect the version?

60. DETECTING THE VERSION

61. LET NGINX DO THE JOB

62. LET NGINX DO THE JOB
$req->getHeader(‘API-Version)

63. LET NGINX DO THE JOB
api.example.com/v1/customers

64. LET NGINX DO THE JOB
api.example.com/customers
API-Version: 1

65. LET NGINX DO THE JOB
Without polluting
your router or controller class

66. “I beg to differ”

67. “I beg to differ”
URL, subdomain,
media type, header...

68. “I beg to differ”
Picking a wrong
implementation
doesn’t matter

69. “I beg to differ”
AT ALL.

70. “I beg to differ”
How it impacts the
design of your
software matters

71. 4. BE PRAGMATIC

72. GET or POST?

73. GET or POST?
api. example.com/login/?username=cirpo&login=wunderbar

74. 5.TESTING

75. cURL is your best friend
curl -X GET https://api.example.com/products
curl -X POST https://api.example com/order -data=”{...}”
curl -X DELETE ...
curl -X PATCH ...

76. cURL is your best friend

77. PHP
cuzzle
cURL command
from Guzzle requests
github.com/namshi/cuzzle

78. cURL is your best friend

79. cURL is your best friend

80. cURL is your best friend

81. HTTPARTY

82. HTTPIE

83. Javascript
mockserver
mock your APIs
in a matter of seconds!
github.com/namshi/mockserver

84. Javascript
mockserver

85. Javascript
users_GET.mock file
mockserver

86. Javascript
mockserver

87. TESTING APIS

88. Android 2.3 native browser…

89. TESTING APIS

90. TESTING APIS
you can even
decrypt the https responses :)

91. Javascript
shisha
smoke tests made easy!
github.com/namshi/shish

92. Javascript
shisha
.smoke file

93. Javascript
shisha

94. 6. DESIGN

95. An API is a layer on
top of your domain

96. Pick the layer that
is most suitable
to your needs

97. HTTP APIs are a
good start

98. REST IS A DREAM!

99. HTTP METHOD
POST or PUT?

100. HTTP METHOD
PUT or PATCH?

101. USER TAGS
/users/johnny/tags

102. USER TAGS
deleting a non-existent tag:
200, 204 or 404?

103. USER TAGS
ON STACKOVERFLOW
THEY’RE
deleting a non-existent tag:
STILL FIGHTING
200, 204 or 404?
http://stackoverflow.com/questions/2342579/http-status-code-for-update-
and-delete

104. be consistent

105. NAMING
/user/1
/users
/order/1
/orders

106. NAMING
/city/1
/cities
/curriculum/1
/curricula

107. NAMING
/user/1
/users
/order/1
/orders
/city/1
/cities
/curriculum/1
/curricula

108. NAMING
/user/1
/users
/order/1
/orders
/city/1
/cities
/curriculum/1
/curricula
NOT GOD AT ALL!

109. STICK WITH PLURALS!

110. NAMING
/users1
/users
/orders/1
/orders

111. NAMING
/cities/1
/cities
/curricula/1
/curricula

112. NAMING
/users/1
/users
/orders/1
/orders
/cities/1
/cities
/curricula/1
/curricula

113. UNIQUE RESOURCES
/users/1
/users/cirpo
/users/A323K833

114. UNIQUE RESOURCES
/orders/15
/orders/A323K833

115. UNIQUE RESOURCES
/orders/15
AVOID INCREMENTAL
NUMBERS
/orders/A323K833
IF IT’S BUSINESS CRITICAL

116. Unstructured APIs
=
API aggregation

117. api.example.org/v1/latest-news

118. latest news +
metatags +
banners +
navigation
yada yada yada

119. Sort of a “wild” API
for your whole app

120. The client receives a GET
on /something
and will let the
API figure out
what /u/something
actually is

121. Orchestration Layers

122. https://engineering.groupon.com/2013/misc/i-tier-dismantling-the-monoliths/

123. “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

124. DOMAIN
users
orders
stock
images

125. DOMAIN
Think about collections
not
controllers

126. DOMAIN
PUT/PATCH
try to always plan for full updates

127. UNIFORM RESPONSES

128. CODEBASE ORGANIZATION

129. CODEBASE ORGANIZATION
one bundle for each api?
one bundle for each application?
one app for each sets of api?

130. CODEBASE ORGANIZATION
start with an app
organize bundles semantically
create shared bundles

132. CODEBASE ORGANIZATION
BUNDLES
product
checkout
warehouse
generic
entity

133. CODEBASE ORGANIZATION
APP
product
BUNDLES
checkout
warehouse
generic
entity

134. 7. SCALABILITY

135. CACHE ALL THE THINGS!

136. MIDDLEWARE

137. MIDDLEWARE - CONNECT

138. MIDDLEWARE - STACK

139. AVOID SESSIONS

140. EVERYTHING AS A RESOURCE

141. 8. ISSUES

142. CORS

143. CORS

144. (silly) browsers

145. if a cross-domain
request is cacheable,
the android browser
goes nuts
(silly) browsers

146. The request does
not include
the Origin header
(silly) browsers

147. Status code: 0
(silly) browsers

148. WHAT. THE. HECK.
http://opensourcehacker.com/2011/03/20/android-webkit-xhr-status-code-0-and-expires-headers/
(silly) browsers

149. “standards”

150. Don’t play with fire

151. 1 API, N clients
consuming it
Don’t play with fire

152. desktop browser,
mobile browser,
ios app, android app...
Don’t play with fire

153. Keep as much logic
as possible on the
server
Don’t play with fire

154. Less things to
implement on every
client and centralized
implementations
Don’t play with fire

155. make it easy for the
API clients
Don’t play with fire

156. 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
Don’t play with fire
{
“email"=>"alessandro.cinelli@gmail.com",
"firstName"=>"Alessandro",
"lastName"=>"Cinelli",
“birthday”=>"14/09/1985",
}

157. Security matters

158. [
"odino@gmail.com",
"cirpo@gmail.com",
...
]
Security matters

159. for(;;);[
"odino@gmail.com",
"cirpo@gmail.com",
...
]
Security matters

160. while(1);[
"odino@gmail.com",
"cirpo@gmail.com",
...
]
Security matters

161. while(1);[
"odino@gmail.com",
"cirpo@gmail.com",
...
]
Security matters

162. Avoid [...]
http://bit.ly/json-hijacking
Security matters

163. USE {…}
Security matters

164. That’s all folks

165. /
github.com/cirpo
@cirpo

166. tech.namshi.com/join-us
we are hiring!
tech.namshi.com
github.com/namshi
twitter.com/TechNamshi

168. THANKS

169. 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