A long presentation on a variety of aspects of REST.

1. REST Explained
Representational State Transfer
Dhananjay Nene
July 4, 2009
TechWeekend – Pune
http://blog.dhananjaynene.com http://twitter.com/dnene

2. What REST is not !

3. REST is not a ..
framework

4. REST is not a ..
technology

5. REST is not a ..
a standards specification

6. REST is an architecture style

7. .. as documented and described by Roy Fielding ..

8. .. which specifies a set of architecture constraints.

9. Fielding on Architecture Style
● An architecture style is a coordinated set of
architectural constraints that restricts the roles
and features of architectural elements, and the
allowed relationships between those elements,
within any architecture that conforms to that
style
● A style can be applied to many architectures
● An architecture can consist of many styles

10. Architecture Constraint 1
Client - Server

11. Client Server
Separates user interface concerns from data
storage concerns

12. Client Server
Improves portability of interface across multiple
platforms

13. Client Server
Improves scalability by simplifying server
components

14. Client Server
Allows the components to evolve independently

15. Architecture Constraint 2
Statelessness
No Client State

16. Statelessness
Each request from client to server must contain all
of the information necessary to understand the
request and cannot take any advantage of any
stored context on the server.
and
Each request contains all of the information
necessary for a connector to understand the
request, independent of any requests that may
have preceded it

17. Statelessness
Session state is therefore kept entirely on the
client

18. Statelessness
Improved visibility since a monitoring system does
not have to look beyond a single request

19. Statelessness
Improved reliability due to easier recoverability
from partial failures

20. Statelessness
Improved scalability due to not having to allocate
resources for storing state

21. Statelessness
Server does not have to manage resource usage
across requests

22. Statelessness
Tradeoff : Reduced Network Performance

23. Statelessness
Tradeoff : Reduced server control over application
consistency

24. Statelessness is one of the most difficult to deal
with constraints
(but more on that later)

25. Architecture Constraint 3
Specified Cacheability

26. Specified Cacheability
Data within a response to a request be implicitly
or explicitly labeled as cacheable or non-
cacheable

27. Specified Cacheability
If a response is cacheable, then a client cache is
given the right to reuse that response data for
later, equivalent requests

28. Specified Cacheability
Improves efficiency, scalability and user perceived
performance

29. Specified Cacheability
Tradeoff : Reduced Reliability

30. Architecture Constraint 4
Uniform Interface

31. Uniform Interface
Overall system architecture is simplified and the
visibility of interactions is improved

32. Uniform Interface
Implementations are decoupled from the services
they provide and encourage independent
evolvability

33. Uniform Interface
Tradeoff : Degrades efficiency
since Information is transferred in a standardised form rather
than one which is specific to application's needs

34. Uniform Interface
Four interface constraints
(more later .. we shall be spending the maximum time on this)
● Identification of resources
● Manipulation of resources through
representations
● Self descriptive messages
● Hypermedia as the engine of application state
(HATEOAS)

35. Architecture Constraint 5
Layered System

36. Layered System
Places a bound on overall system complexity

37. Layered System
Promotes substrate independence

38. Layered System
Can be used to encapsulate legacy services or
protect new services from legacy clients

39. Layered System
Intermediaries can be used to improve system
scalability by enabling load balancing

40. Layered System
Tradeoff : Add overhead and latency and reduce
user perceived performance

41. Layered System
Placing shared caches at boundaries of
organisational domain can result in significant
benefits. Can also enforce security policies eg.
firewalls

42. Layered System
Intermediaries can actively transform message
content since messages are self descriptive and
their semantics are visible to the intermediaries

43. Architecture Constraint 5
Code on demand
(is an optional constraint)

44. Code on demand
Client functionality can be extended by
downloading and executing code in the form of
applets or scripts

45. Lets get back to .. and explore in far more detail ..

46. Interface constraints of ReST

47. Resources

48. Resources
What are resources ?

49. Any information that can be named is a resource

50. A resource is a conceptual mapping to a set of
entities not the entity itself. Such a mapping can
change over time.

51. This presentation is a resource

52. As is this presentation's latest version (if I am
regularly backing it up to different files)

53. All available presentations on ReST is also a
resource. A resource can be a collection of
entities too.

54. Resource Identifiers

55. Every resource has a name that uniquely
identifies it – the URI

56. Names don't change
(at least not frequently)

57. Think of it like a primary key for each row in a
database
http://informationbase/locationdb/citiestable/pune

58. REST doesn't dictate URI choice.
Leaves it to the application author.

59. The URI should generally carry no meaning to the
client except as a resource locator

60. However don't let that encourage you to name
URIs arbitrarily and confusingly

61. Good, clean, structured URIs are helpful for
developers

62. If you are naming a specific single resource all the
information to locate the resource should be in the
URI itself and not through additional parameters

63. eg. choose
http://informationbase/locationdb/citiestable/pune
not
http://informationbase/locator?type=city&name=pune

64. However optional parameters for identifying
subsets of resources are conventionally
acceptable

65. eg.
http://ibase/cities?startswith=pu&start=11&count=10

66. Resources have Representations

67. A representation captures the current or intended
state of a resource

68. Resources are transferred between the client and
the server

69. Resources may include metadata describing
themselves

70. A particular resource may have multiple
representations

71. Commonly used representation formats are
html, xml and json
however they could also be pdf, png etc.

72. When multiple resource formats are supported by
the server, the actual resource format returned is
subject to content negotiation between the client
and the server

73. This should ideally happen through control data
i.e. By using HTTP “Accept” headers and not by
appending additional information to the URL.
Prefer
Accept: text/xml;q=0.5, application/json
http://infobase/cities/pune
to
http://infobase/cities/pune.json

74. REST doesn't dictate or constrain you to using
particular representation formats. Use what suits
the application context the best.

75. Interface constraint 3
Self descriptive messages

76. Requests and responses contain inband
description about the schema it adopts

77. This is done by describing the XML Schema for
the representation (or its units) using the same by
declaring its appropriate XML namespace. Further
clarity can be introduced by using a custom
“application/vnd.*****” Content-Type header.

78. The entire schema does not need to be known
upfront. Only the mandatory and relevant parts
need to be known.

79. The schema can continue to be extended without
client modifications if it is only adding optional
elements or attributes.

80. Intermediate layers can both parse and transform
messages intelligently

81. Metadata helps both page and form rendering and
client side validations could be introduced based
on an understanding of the schema and its
semantics

82. Interface constraint 4
Hypermedia as the engine of application state
(HATEOAS)

83. Hypermedia
Hypermedia is used as a logical extension of the
term hypertext in which graphics, audio, video,
plain text and hyperlinks intertwine to create a
generally non-linear medium of information.
source : Wikipedia

84. HyperText
Simultaneous presentation of information and
controls such that the information becomes the
affordance through which the user obtains
choices and selects actions
- Roy Fielding

85. Application State
state that determines "where" the user is in the
process of completing a task
It is not the resource or state of the resource on
the server

86. To understand application state, you need to
visualise the pages / resources of the application
as a wireframe model or a state machine and
each page as a state

87. Each state allows for only a few valid triggers to
allow it to navigate to another state

88. These possible navigations out of the state can be
embedded in the resource representation
overlying the state by using hypertext (links)

89. Since each state self describes the possible links
given the context, the client can choose to select
the appropriate link by examining the link
metadata.

90. To put it differently
Make hypermedia constrain client choices, and
the client choice influences the application state

91. Therefore :
Hypermedia as the engine of application state

92. Client needs to know only the starting URL

93. In addition client needs to be able to understand
the mediatypes and semantics associated with
the links (ie. What does a link with a particular
“rel” type mean)

94. One more aspect of Uniform Interfaces

95. Uniform Operations

96. In case of database tables, these are
Insert, Select, Update, Delete

97. In common parlance these are
Create, Read, Update, Delete (CRUD)

98. In REST over HTTP these are
POST, GET, PUT, DELETE

99. Those are the only verbs you need

100. Simplifies semantics

101. Simplifies client complexity

102. Simplifies application model

103. Clients interact with REST based systems by
sequentially performing one of POST, GET, PUT,
DELETE operations on self describing resources
and by traversing the links offered by the server

104. For this clients need to understand resource
representation schemas (xml schemas) and ...

105. Client need to understand semantics of the
relationship types (<link rel=”...”>) offered by the
server

106. REST is the DBMS of the internet

107. With a slight caveat

108. It doesn't break encapsulation

109. It exposes resource representations and not
resources themselves

110. Thats like a parallel set of tables / views that
clients can access and which have triggers which
in turn appropriately update the real tables

111. Its often much easier and quicker to understand
table schemas than it is to understand stored
procedure semantics

112. This is an important distinction compared to RPC/
SOA based architectures which in case of this
analogy would represent stored procedures

113. Which is why a client is likely to be far quicker off
the starting block if given a set of schemas and
standard SQL semantics to work with rather than
a list of stored procedures describing each
procedure, its parameters and the
interrelationships between the procedures.
Thats what makes ReST so much easier for its
clients and users

114. Sample ReST request

115. Sample ReST response

116. ReST simplifies

117. ● Hypertext is standardised. Fewer UIs
● Identification is standardised. Lesser
communication
● Exchange protocols are standardised. Fewer
Integrations
● Interactions are standardised. Fewer semantics
● Data formats are standardised. Fewer
translations
- Roy Fielding

118. No IDLs, WADLs, WSDLs

119. No static compilations required

120. No methods and what each method means

121. No inter method sequencing

122. No registries

123. When dealing with complex stuff,
you always feel,
you can use some rest.

124. When you use ReST, things are simpler

125. Benefits of REST
- Roy Fielding

126. Uniform resources having identifiers increases
reuse potential

127. Uniform interface hides implementation details
supporting low coupling

128. Hypertext allows for late binding leading to
reduction in attempted inappropriate accesses
and resultant errors

129. Server failures don't befuddle client state leading,
while shared state is easily recoverable leading to
improved fault tolerance

130. Supports gradual and fragmented change across
organisations.

131. Services can be layered, clustered and cached
leading to improved scalability

132. ReST extends the very capabilities that made
WWW successful into application design and
architecture

133. What are these characteristics of static W W W
and ReST?

134. You can connect to any web server if you know
the home page URL
You can connect to ReST application if you know
the starting URI

135. On the home page you can view the content
along with the appropriate hyperlinks which
suggest appropriate paths for you to traverse
The response will provide you important initial
content along with hyperlinks which describe their
nature to navigate to other resources

136. You can navigate to the next page by clicking on
the hyperlink
You can conduct an operation by performing a
POST/GET/PUT/DELETE on one of the
suggested URIs

137. You can save the hyperlink URL, bookmark it or
email it to you boss or tweet it to your friends
A ReST client can store a URI for future use or
embed it as a foreign key in other resources that it
maintains

138. They will not need to repeat your sequence of
steps. They will be able to directly access the
page given the URL.
The receiving ReST client will be able to directly
access the earlier stored URI without going
through a sequence of pages

139. You can save the contents of any page by saving
its HTML representation
You can save the representation of any resource
into a XML / Document database

140. You can modify the contents of the web pages by
entering data in forms (and even full page content
in blogs, Wikis etc.) and POSTing them.
You can perform PUT, POST and DELETE
operations on resources to modify them

141. You can upload new files by browsing for the file
on your desktop and submitting the button on
appropriately configured pages (PUT file)
You can add new resources by conducting the
POST operation

142. The server retains no information about the pages
you've traversed
The server retains no information about you or the
pages you've traversed

143. The server can send you different media types
(eg. HTML, PDF, Videos etc.) by describing these
media types in the headers
The server sends the metadata describing the
resource representation inband with the
representation

144. Did you notice there is no global internet registry
for website discovery ?
There is no registry required for ReST
applications

145. Yahoo tried, as does Open Directory but it just
doesn't work
And it may not for many other architectures
requiring registries

146. Since the content depends on basic HTML tags
and each URL is uniquely addressable, it is easy
for search engines to index its content and allow
users to find the required pages
Representations for URIs can be browsed,
indexed and eventually searched through

147. These are all characteristics that made static www
simple to use, deploy and leverage making it
popular and eventually omnipresent
These are also characteristics of ReST
contributing to its simplicity and ease of
leveraging accounting for its popularity

148. Designing ReSTful applications

149. Using a ReST supportive framework does not
make your application ReSTful

150. You need to model your application interfaces as
a set of resources

151. And basic CRUD operations on these resources

152. Since controllers in traditional web frameworks
drive the interface, we shall focus on these

153. When the interface is meant for browsers, there
are some limitations. Hence browser oriented
interfaces are a little different than POST, GET,
PUT, DELETE

154. Assuming each controller represents a lifecycle
manager for a particular resource type, it needs a
few basic methods. And the same methods get
reproduced across all such controllers

155. Resource URI HTTP Controller Description
Method Method
/cities GET index Get list of cities (optional params)
/cities POST create Create a new city
/cities/Pune GET show Show pune resource representation
/cities/Pune PUT update Modify pune resource
/cities/Pune DELETE destroy Delete pune resource
/cities/new GET new Initiate a new city resource creation
/cities/Pune;edit GET edit Initiate a new city modification

156. No more actions like
city.expand (CityExpansion.create) ,
city.holdElections (CityElection.create) etc.

157. You will need to create new controllers which
represent new nouns representing the action

158. Not all controllers will implement all methods. But
they should not implement any more methods.

159. As you move from an action oriented design
towards resource oriented design, thinking of
everything as nouns is one of the early challenges
to overcome

160. Transaction.approve becomes TransactionApproval
Account.pay become AccountPayment.create
etc. etc.

161. For each resource you need to document the
XML Schema and define a mime type
(application/vnd.***)
especially when the consumer is a machine

162. For each resource representation you need to list
what are the appropriate URIs (application state
transitions) to be returned along with the
representations and implement introduction of
these in the controller actions as well

163. REST and Security

164. This is one area where I choose to be non
ReSTful

165. Sometimes the deliberate requirements of
opaqueness of security and transparency of ReST
don't cooperate well

166. Cookies
Cookie interaction fails to match REST's model of
application state, often resulting in confusion for
the typical browser application.
- Roy Fielding

167. I agree with that .. but ...

168. Cookies can help in user identification (other
options being Basic HTTP authentication)

169. Basic HTTP Authentication is weak

170. Computes a hash which can be intercepted and
reused later

171. If you do use Basic HTTP authentication at the
minimum use HTTPS

172. But I prefer cookies when they are strictly used for
user identification only

173. But cookies break the statelessness model

174. Yes they do. I prefer to store only the data thats
expensive to compute but can be recomputed in
case of loss in the session against the cookie. No
storage of conversational state in the session

175. That is hard to ensure .. and thats another self
imposed architecture constraint

176. But I think it is more practical for secure
applications

177. Even though it takes away their ability of being
called 100% ReSTful

178. What about alternative architecture styles (SOA) ?

179. They are an extension of the RPC construct not
the www construct

180. They simply do not have most of the benefits I just
referred to

181. And the hype-engine is really struggling to
compete with the wide successes of ReST

182. Experience has shown when sites offered both
SOA and ReST interfaces, clients quickly ended
up choosing ReST
- sounds intituitive enough to me
but do not recollect the source.

183. Rest is not SOA

184. They both attempt to solve a similar set of
problems ....

185. .... differently!

186. ● ReST requires you to think resources not
actions or services
● ReST requires you to lay a greater emphasis on
documentation of your schema and practically
none on the actions
● ReST requires you to provide in band metadata
● ReST works very nicely with layered
architectures
● Another way to describe ReST is ROA :
Resource Oriented Architecture

187. The clear distinctions between ROA and SOA are
being blurred for non technical reasons. Be
aware when you read content debating
ReST/SOA
(including this presentation)

188. SOA is the evolution of RPC semantics
ReST / ROA is the evolution of www semantics

189. A look forward to increasing ReST popularity

190. ReST already is starting to dominate the internet
space and there's a good likelihood it could
dominate enterprise architectures as well.

191. References and Sources
● Roy Fielding's Dissertation on ReST
● A little REST and Relaxation : presentation by Roy Fielding
● Pragmatic Intro to REST and SOA, REST and the Web:
presentations by Stephan Tilkov
● Pragmatic REST And RESTful Web Apps: presentations by
Subbu Allamaraju
● Describing RESTful applications : Article by Subbu Allamaraju at
InfoQ.
● RESTful Best Practices : presentation by calamitas
● The REST architectural style : presentation by Robert Wilson

192. Thank You !