Presented on 4Developers 2013 (12th April).

1. DESIGNING BEAUTIFUL
REST APIs
@tomekcejner

2. THE PRESENTER

3. THE PRESENTER
TOMEK CEJNER
@tomekcejner
www.japko.net
tomek@japko.net

4. THE PRESENTER
TOMEK CEJNER
@tomekcejner
www.japko.net
tomek@japko.net

5. FASHION

6. WHAT REST MEANS

7. NO FRAMEWORKS

8. APPLICATIONS

9. APPLICATIONS
GOING OPEN

10. APPLICATIONS
GOING OPEN
GOING BIG

11. SOA

12. LOOSE COUPLING

13. LOOSE COUPLING
SMALLER CODEBASE

14. LOOSE COUPLING
SMALLER CODEBASE
REUSABILITY

15. WEB SERVICES

17. WORLDS BIGGEST APP EVER

18. WORLD WIDE WEB

19. WHAT IS REST?

20. A PROTOCOL?

21. A PROTOCOL?
NO

22. A SPECIFICATION?

23. A SPECIFICATION?
NO

24. ARCHITECTURAL STYLE

25. ROY T. FIELDING
PHD DISSERTATION

26. http://www.w3.org/Protocols/rfc2616/rfc2616.html

28. BUILDING ARCHITECTURE

29. BUILDING ARCHITECTURE
FROM SCRATCH

30. BUILDING ARCHITECTURE
FROM SCRATCH
FROM WHOLE

32. CONSTRAINTS

33. CONSTRAINTS
CLIENT-SERVER

34. CONSTRAINTS
CLIENT-SERVER
STATELESS

35. CONSTRAINTS
CLIENT-SERVER
STATELESS
CACHEABLE

36. CONSTRAINTS
CLIENT-SERVER
STATELESS
CACHEABLE
UNIFORM INTERFACE

37. RESOURCE

38. URI
http://www.example.com/blogs/423/entries/12340
http://www.example.com/sales/2004/Q4
http://www.example.com/bugs/by-state/open

39. URI
http://api.example.com/places/42.089199,93.076172
http://api.example.com/color-blends/yellow;blue

40. URI
http://api.example.com/items?price_min=0&price_max=599

41. URI
http://api.example.com/auctions/239841/cancel

42. URI
http://api.example.com/auctions/239841/cancel

43. RICHARDSON MATURITY MODEL
http://www.crummy.com/writing/speaking/2008-QCon/act3.html

50. LEVEL 0

51. LEVEL 0
HELL

52. POST /auctionServiceAPIEndpoint HTTP/1.1
<query>
<params>
<name>Macbook Air</name>
<price_from>0</price_from>
<price_to>1000</price_to>
</params>
</query>

53. HTTP/1.1 200 OK
<items>
<item>
<id>123</id>
<name>Macbook Air</name>
<price>499</price>
<condition>NEW</condition>
</item>
</items>

54. LEVEL 1

55. LEVEL 1
URI

56. POST /auctions/1234/read

57. POST /auctions/1234/read
GET /auctions/1234/read

58. POST /auctions/1234/read
GET /auctions/1234/read
POST /auctions/create

59. POST /auctions/1234/read
GET /auctions/1234/read
POST /auctions/create
POST /auctions/1234/update

60. LEVEL 2
HTTP

61. /auctions

62. /auctions
/auctions/1234

63. GET

64. GET
POST

65. GET
POST
PUT

66. GET
POST
PUT
DELETE

67. GET
POST
PUT
DELETE
HEAD

68. GET
POST
PUT
DELETE
HEAD
OPTIONS

69. GET
POST
PUT
DELETE
HEAD
OPTIONS
PATCH

70. GET

72. GET /auctions

73. GET /auctions
GET /auctions/1234

74. GET /auctions
GET /auctions/1234
GET /auctions?search=Macbook+Air

75. SAFE + IDEMPOTENT

77. TESLA MODEL S
IT HAS A RESTFUL API

79. GET http://api.flickr.com/services/rest?
method=flickr.photos.people.add&api_key=xxx&photo_id=yyy&user
_id=zzz

80. DELETE

81. DELETE
DELETE /auctions/1234

82. DELETE
DELETE /auctions/1234
HTTP/1.1 204 No Content

83. DON’T DO THIS AT HOME

84. DELETE

85. DELETE
IDEMPOTENT

86. DELETE
IDEMPOTENT
NOT SAFE

87. POST

88. POST /items
{
! "name" : "Macbook Air 2010",
! "condition" : "NEW",
! "price" : 499
}

89. POST /items
{
! "name" : "Macbook Air 2010",
! "condition" : "NEW",
! "price" : 499
}
201 Created
Location: http://api.alledrogo.com/items/1235

90. POST

91. POST
NOT IDEMPOTENT

92. POST
NOT IDEMPOTENT
NOT SAFE

93. PUT

94. PUT /items/1235
{
"name" : "Macbook Air 2010",
! "condition" : "LIKE_NEW",
! "price" : 498
}

95. PUT /users/joe
{
“first_name” : “Joe”,
“last_name” : “Smith”
}

96. PUT
IDEMPOTENT
NOT SAFE

97. POST: ID FROM SERVER

98. POST: ID FROM SERVER
PUT: ID FROM CLIENT

99. OPTIONS

100. OPTIONS
DISCOVERY

101. OPTIONS /users HTTP/1.1
...
HTTP/1.1 204 No Content
Allow: GET, POST, PUT

102. /users /users/456
GET GET ALL GET USER
POST CREATE NEW -
PUT - UPDATE
DELETE DELETE ALL DELETE USER

103. HTTP STATUS CODES

104. SUCCESS

105. SUCCESS
200 OK

106. SUCCESS
200 OK
201 CREATED

107. SUCCESS
200 OK
201 CREATED
202 ACCEPTED

108. SUCCESS
200 OK
201 CREATED
202 ACCEPTED
204 NO CONTENT

109. 201 CREATED
POST /items/1234/bids
{
! "amount" : 602.99
}
201 Created
Location: http://api.alledrogo.com/items/1234/bids/100001
{
! "cap_amount" : 602.99,
! "current_bid" : 510,
! "winning" : true
}

110. REDIRECT

111. REDIRECT
301 MOVED PERMANENTLY

112. REDIRECT
301 MOVED PERMANENTLY
303 SEE OTHER

113. REDIRECT
301 MOVED PERMANENTLY
303 SEE OTHER
304 NOT MODIFIED

114. REDIRECT
301 MOVED PERMANENTLY
303 SEE OTHER
304 NOT MODIFIED
307 TEMPORARY REDIRECT

115. USER ERROR

116. USER ERROR
400 BAD REQUEST

117. USER ERROR
400 BAD REQUEST
401 UNAUTHORIZED

118. USER ERROR
400 BAD REQUEST
401 UNAUTHORIZED
403 FORBIDDEN

119. http://cropp.com/404

120. 405 METHOD NOT ALLOWED

121. 409 CONFLICT

122. 410 GONE

123. SERVER ERROR

124. SERVER ERROR
500 INTERNAL SERVER ERROR

125. SERVER ERROR
500 INTERNAL SERVER ERROR
503 SERVICE UNAVAILABLE

126. DON’T IGNORE HTTP STATUS

127. DON’T IGNORE HTTP STATUS
http://api.flickr.com/services/rest?
method=flickr.photos.people.add&api_key=xxx&photo_id=yyy&user_id=zzz

128. DON’T IGNORE HTTP STATUS
http://api.flickr.com/services/rest?
method=flickr.photos.people.add&api_key=xxx&photo_id=yyy&user_id=zzz
HTTP/200 OK

129. DON’T IGNORE HTTP STATUS
http://api.flickr.com/services/rest?
method=flickr.photos.people.add&api_key=xxx&photo_id=yyy&user_id=zzz
HTTP/200 OK
<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="fail">
<err code="100" msg="Invalid API Key (Key has invalid format)" />
</rsp>

130. LEVEL 3

131. LEVEL 3
HYPERMEDIA

132. LINKING

134. SELF DESCRIBED
CAPABILITIES
INTERCONNECTION

135. PRESENTATION
XHTML
XML
ATOM
...

136. NO HYPERMEDIA
GET /items?q=macbook+air+new
{
! "results" : [
! ! {
! ! ! "id" : 1234,
! ! ! "name" : "Macbook Air 2010 LIKE NEW",
! ! ! "price" : "499"
! ! }
! ]
}

137. WITH HYPERMEDIA
GET /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"
! ! }
! ]
}

138. 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"
}

139. 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"
}

140. POST /items/1234/bids
{
! "amount" : 602.99
}

141. POST /items/1234/bids
{
! "amount" : 602.99
}
201 Created
Location: 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
}

142. DOMAIN APPLICATION PROTOCOL

143. HATEOAS

144. HATEOAS
HYPERMEDIA

145. HATEOAS
HYPERMEDIA
AS

146. HATEOAS
HYPERMEDIA
AS
THE ENGINE

147. HATEOAS
HYPERMEDIA
AS
THE ENGINE
OF APPLICATION STATE

148. IN PRACTICE

149. AUCTION SERVICE - USERS

150. AUCTION SERVICE - USERS
doGetMyData
doGetUserID
doGetUserItems
doShowUser
doShowUserPage

151. AUCTION SERVICE - USERS
doGetMyData GET /users/me
doGetUserID GET /users?name=czesio
doGetUserItems GET /users/123456/items
doShowUser GET /users/123456/details
doShowUserPage GET /users/123456/aboutpage

152. AUCTION SERVICE - MY AUCTIONS

153. AUCTION SERVICE - MY AUCTIONS
doGetFavouriteCategories
doGetFavouriteSellers
doGetMyBidItems
doGetMyWatchItems
doGetMySoldItems
doRemoveFromWatchList

154. AUCTION SERVICE - MY AUCTIONS
doGetFavouriteCategories GET /users/me/favorites/category
doGetFavouriteSellers GET /users/me/favorites/sellers
doGetMyBidItems GET /users/me/bids
doGetMyWatchItems GET /users/me/items/watching
doGetMySoldItems GET /users/me/items/sold
doRemoveFromWatchList DELETE /users/me/items/watching/1

155. AUCTION SERVICE - BIDDING

156. AUCTION SERVICE - BIDDING
doBidItem
doRequestCancelBid

157. AUCTION SERVICE - BIDDING
doBidItem POST /items/54321/bids
doRequestCancelBid DELETE /items/54321/bids/678

158. BEYOND CRUD

159. COPY
GET /items/5001
HTTP/1.1 200 OK
{
“_links” : [
{ “rel” : “self”,
“href” : “/items/5001”
},
{ “rel” : “duplicate”,
“href” : “/items/5001/duplicate;t=37489231614874”
}
],
“name” : “MacBook Air”,
“price” : 599
}

160. COPY
POST /items/5001/duplicate;t=37489231614874
HTTP/1.1 201 Created
Location: /items/5002

161. SNAPSHOT
PUT /items/5002
{
“name” : “MacBook Air”,
“price” : 399
}
HTTP/1.1 204 No Content

162. SNAPSHOT
GET /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
}

163. UNDO
POST /items/5002/undo;t=92312093
HTTP/1.1 303 See Other
Location: /items/5002

164. ASYNCHRONOUS OPERATION

165. ASYNCHRONOUS OPERATION
POST /projects/123/tasks
{
“type” : “REPORT”,
“date_from” : “20130101”,
“date_to” : “20130331”
}

166. ASYNCHRONOUS OPERATION
POST /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” },
]
}

167. MEDIA TYPES

168. MEDIA TYPES
Content-Type: application/vnd.alledrogo+xml

169. MEDIA TYPES
Content-Type: application/vnd.alledrogo+xml
Content-Type: text/html

170. REST VS SOAP/RPC

171. REST VS SOAP/RPC
COMPLEMENT, NOT CONCURRENT

172. NATURE OF THE WEB

173. CALL IT REST

174. CALL IT REST
WHEN DOING IT REST

175. THANK YOU!