The document discusses the key architectural constraints of REST (Representational State Transfer), including client-server architecture, stateless servers, cacheable responses, and a uniform interface. It explains how these constraints enable REST architectures to be scalable, simple, visible, and reliable. The uniform interface constraint is discussed in depth, covering identification and manipulation of resources through representations.
4. REpresentational State Transfer
REST
GET /hist
…
4
cat http.log | grep GET
GET /hist
PUT /doc/1
…
cat http.log grep GET
stdout stdin
stdout
∅
5. «An architectural style is a … set of
CONSTRAINTS that restricts the roles of
REpresentational State Transfer
REST
5
architectural elements …»
Roy T. Fielding, 2000
17. REpresentational State Transfer
REST
17
1. Client - Server
POST /hotels/lviv/nobilis/suite-room/booking
…
!
{
«from»: «2014-09-10»,
«to»: «2012-09-20»,
«breakfast»: true
}
request
18. REpresentational State Transfer
REST
17
1. Client - Server
POST /hotels/lviv/nobilis/suite-room/booking
…
!
{
«from»: «2014-09-10»,
«to»: «2012-09-20»,
«breakfast»: true
}
request
201 Created
…
!
{
«id»: «123»,
«from»: «2014-09-10»,
«to»: …
}
response
19. REpresentational State Transfer
REST
18
1. Client - Server
Separation of Concerns:
!
• Client responsible for UI
• Server responsible for data storage
24. REpresentational State Transfer
REST
22
Application State
Where you ARE in the
interaction / session
Pending Confirmed
Served
create
update
rejected
cancel Cancelled
"live"
confirmed
Rejected
update
delete
26. REpresentational State Transfer
REST
24
2. Stateless Server
• Each request contains ALL the
information necessary to understand it
!
• Application (session) state is kept on
the client
32. GET /hotels
Cookie: JSESSIONID=987 request
REpresentational State Transfer
REST
26
2. Stateful Server
POST /session request
response Set-Cookie: JSESSIONID=987
{
«hotels»: <1..25>
} response
33. GET /hotels
Cookie: JSESSIONID=987 request
GET /hotels/next
Cookie: JSESSIONID=987 request
REpresentational State Transfer
REST
26
2. Stateful Server
POST /session request
response Set-Cookie: JSESSIONID=987
{
«hotels»: <1..25>
} response
{
«hotels»: <26..50>
} response
48. REpresentational State Transfer
REST
35
Web < 1994
- Static documents
- CERN libwww common library
- No consistent set of semantics
for all resources
51. REpresentational State Transfer
REST
38
4. Uniform Interface
1. Identification of resources
2. Manipulation of resources through
representations
3. Self-descriptive messages
4. HATEOAS
52. 4. Uniform Interface
REpresentational State Transfer
REST
39
Resource
is a key abstraction
66. 4. Uniform Interface
Resources
REpresentational State Transfer
REST
49
/v1
/v2 /v3
/latest
/v2 != /latest
/v3 != /latest
67. 4. Uniform Interface
Resources
REpresentational State Transfer
REST
50
=> {}
=> static:
!
=> dynamic:
68. 4. Uniform Interface
Resources
REpresentational State Transfer
REST
51
+ Generality
+ Allows late binding
+ Allows to reference
concept, not singular
representation
72. 4. Uniform Interface
Content Negotiation = Conneg
REpresentational State Transfer
REST
55
GET /current-time
Accept: text/plain request
73. 4. Uniform Interface
Content Negotiation = Conneg
REpresentational State Transfer
REST
55
GET /current-time
Accept: text/plain request
200 OK
Content-Type: text/plain
!
Thu Aug 30 2014 09:30:15 GMT+0300 (EEST)
response
74. 4. Uniform Interface
Conneg
REpresentational State Transfer
REST
56
GET /current-time
Accept: text/xml request
75. 4. Uniform Interface
Conneg
REpresentational State Transfer
REST
56
GET /current-time
Accept: text/xml request
200 OK
Content-Type: text/xml
!
<current-time>1341095876929</current-time>
response
76. REpresentational State Transfer
REST
57
GET /current-time
Accept: text/plain;q=0.8,
text/xml;q=0.9
request
4. Uniform Interface
Conneg
77. 4. Uniform Interface
Conneg
REpresentational State Transfer
REST
57
GET /current-time
Accept: text/plain;q=0.8,
text/xml;q=0.9
request
200 OK
Content-Type: text/xml
!
<current-time>1341095876929</current-time>
response
78. REpresentational State Transfer
REST
58
4. Uniform Interface
Representation Structure
200 OK
Content-Type: text/plain
Content-Length: 41
!
Thu Aug 30 2014 09:30:15 GMT+0300 (EEST)
79. Metadata
REpresentational State Transfer
REST
58
4. Uniform Interface
Representation Structure
200 OK
Content-Type: text/plain
Content-Length: 41
!
Thu Aug 30 2014 09:30:15 GMT+0300 (EEST)
80. Metadata
REpresentational State Transfer
REST
58
4. Uniform Interface
Representation Structure
200 OK
Content-Type: text/plain
Content-Length: 41
!
Thu Aug 30 2014 09:30:15 GMT+0300 (EEST)
Data
81. 4. Uniform Interface
REpresentational State Transfer
REST
59
Content-Type drives
processing of the payload,
NOT the payload itself
82. • = Data Format
• Intention:
• Automated processing (JSON, XML)
• Rendered / viewed by a user (HTML)
• Both
• Composite Media Types
• Affects Latency
REpresentational State Transfer
REST
60
4. Uniform Interface
Media Types (Content-Type)
83. 4. Uniform Interface
Control Data
• Defines purpose of the message
GET
REpresentational State Transfer
REST
61
• Used to parameterize request
(e.g. caching)
If-Modified-Since: Sat, 29 Oct 1994
19:43:31 GMT
110. REpresentational State Transfer
REST
64
4. Uniform Interface
REST ≠ CRUD
• CRUD represent operations on data
• CRUD pushes business logic to caller
111. 4. Uniform Interface
REpresentational State Transfer
REST
65
PUT or
POST
for Create/Update?
112. 4. Uniform Interface
REpresentational State Transfer
REST
66
PUT/POST Guidelines
• Use POST to create a resource identified by
a service-generated URI
• Use POST to append a resource to (or to
update existing resource in) a collection
identified by a service-generated URI
• Use PUT to create or update a resource
identified by a URI received by the client
sending full content of the specified
resource
113. 4. Uniform Interface
REpresentational State Transfer
REST
67
POST
POST /bookings
{
«room-id»: «lviv:nobilis:suite»,
«data»: {
«from»: «2014-09-10»,
«to»: «2012-09-20»,
«breakfast»: true
}
}
request
201 Created
Location: /bookings/1
{
«id»: «123»,
«room-id»: «lviv:nobilis:suite»,
«data»: …
}
response
114. 4. Uniform Interface
REpresentational State Transfer
REST
67
POST
POST /bookings
{
«room-id»: «lviv:nobilis:suite»,
«data»: {
«from»: «2014-09-10»,
«to»: «2012-09-20»,
«breakfast»: true
}
}
request
201 Created
Location: /bookings/1
{
«id»: «123»,
«room-id»: «lviv:nobilis:suite»,
«data»: …
}
response
115. 4. Uniform Interface
REpresentational State Transfer
REST
67
POST
POST /bookings
{
«room-id»: «lviv:nobilis:suite»,
«data»: {
«from»: «2014-09-10»,
«to»: «2012-09-20»,
«breakfast»: true
}
}
request
201 Created
Location: /bookings/1
{
«id»: «123»,
«room-id»: «lviv:nobilis:suite»,
«data»: …
}
response
116. 4. Uniform Interface
REpresentational State Transfer
REST
68
PUT
PUT /user/mykola/address
{
«street»: «M. Grinchenko»,
«house»: «2/1»
}
request
200 OK / 204 No Content
{
«street»: «M. Grinchenko»,
«house»: «2/1»
}
response
117. 4. Uniform Interface
4.3. Self-descriptive messages
REpresentational State Transfer
REST
69
Each message includes enough
information to describe how to process
the message
200 OK
Content-Type: application/json
Cache-Control: max-age=3600, must-revalidate
!
{
«hotels»: <1..25>,
…
}
118. 4. Uniform Interface
4.4. HATEOAS
REpresentational State Transfer
REST
70
Application state transitions fully
driven by hypermedia
124. 5. Layered System
REpresentational State Transfer
REST
73
Each component does not «see»
beyond the immediate layer
!
Intermediaries:
• Proxies
• Gateways
141. REpresentational State Transfer
REST
85
Level 0 - Book
POST /bookings
{
«createBooking»: {
«room-id»: «lviv:nobilis:suite»,
«data»: {
«from»: «2014-09-10»,
«to»: «2012-09-20»,
«breakfast»: true
}
}
}
request
200 OK
{
«success»: {
«id»: «123»,
«room-id»: «lviv:nobilis:suite»,
«data»: …
}
}
response
142. REpresentational State Transfer
REST
86
Level 0 - Get Booking
POST /bookings
{
«getBooking»: {
«id»: «123»
}
}
request
200 OK
{
«success»: {
«id»: «123»,
«room-id»: «lviv:nobilis:suite»,
«data»: …
}
}
response
143. REpresentational State Transfer
REST
87
Level 0
1. Single URI endpoint
2. Single HTTP method
3. Uses HTTP as transport, not app protocol
4. Does not use mechanics of the Web
5. Usually based on RPC
Flickr SOAP API,
Google AdSense API
144. REpresentational State Transfer
REST
88
Level 1 - Book
POST /hotel/lviv/nobilis/suite
{
«createBooking»: {
«from»: «2014-09-10»,
«to»: «2012-09-20»,
«breakfast»: true
}
}
request
200 OK
{
«success»: {
«id»: «123»,
«room-id»: «lviv:nobilis:suite»,
«data»: …
}
}
response
145. REpresentational State Transfer
REST
89
Level 1 - Get Booking
POST /bookings/123
{
«getBooking»: {
«id»: «123»
}
}
request
200 OK
{
«success»: {
«id»: «123»,
«room-id»: «lviv:nobilis:suite»,
«data»: …
}
}
response
146. REpresentational State Transfer
REST
90
Level 1
1. Multiple resources
2. Single HTTP method
3. Action in URI or payload
Flickr «REST» API,
Amazon SimpleDB
147. REpresentational State Transfer
REST
91
Level 2 - Book
POST /hotel/lviv/nobilis/suite/booking
{
«from»: «2014-09-10»,
«to»: «2012-09-20»,
«breakfast»: true
}
request
200 OK
{
«id»: «123»,
«room-id»: «lviv:nobilis:suite»,
«data»: …
}
response
148. REpresentational State Transfer
REST
92
Level 2 - Get Booking
GET /bookings/123
request
200 OK
{
«id»: «123»,
«room-id»: «lviv:nobilis:suite»,
«data»: …
}
response
149. REpresentational State Transfer
REST
93
Level 2
1. Many URIs
2. Many verbs
3. But NO hypermedia
Amazon S3
Twitter API
Google Calendar API
150. REpresentational State Transfer
REST
94
Level 2 APIs
HTTP-based Type 1 HTTP-based Type 2
Identification of Resources Yes Yes
Manipulation of Resources through
Representations Yes Yes
Self-Descriptive Messages No Yes
HATEOAS No No
Examples Twitter API Google Calendar API
154. «If the engine of application state (and
hence the API) is not being driven by
hypertext, then it cannot be RESTful and
REpresentational State Transfer
REST
98
cannot be a REST API. Period.»
Roy T. Fielding, 2008
158. {
«take-a-rest:hotel»: {
«href»: «http://localhost:8080/api/hotels/2»,
«mediaType»: «application/hal+json»
}
}
REpresentational State Transfer
REST
102
link
‣ URI - identifies a resource with which the
consumer can interact to progress the application
protocol
‣ rel - contains semantic markup (=> verb, headers,
structure of the payload)
‣ mediaType - format of the payload
159. REpresentational State Transfer
REST
103
Legal interactions between consumer and a set
of resources involved in a business process
Pending Confirmed
Served
create
update
rejected
cancel Cancelled
"live"
confirmed
Rejected
update
delete
Domain Application
Protocol
170. «REST doesn’t eliminate the need for a
clue. What REST does is concentrate that
need for prior knowledge into readily
standardizable forms. That is the essential
distinction between data-oriented and
REpresentational State Transfer
REST
114
control-oriented integration.»
Roy T. Fielding, 2008
171. «... It has value because it is far easier to
standardize representation and relation
types than it is to standardize objects
and object-specific interfaces ...»
REpresentational State Transfer
REST
Roy T. Fielding, 2008
115
172. REpresentational State Transfer
REST
116
profit
• API: explorable & self-documented
• Client:
• No URL construction
• No domain logic replication
• Less coupling
• Server:
• Transparent resource relocation
• Easier versioning & evolvability
175. URI Template Contract
REpresentational State Transfer
REST
119
URL Methods
/api/bookings GET, POST
/api/bookings/{id} GET, POST, PUT, DELETE
/api/hotels GET
/api/hotels/{id} GET
176. URI Template Contract
NOT HATEOAS
REpresentational State Transfer
REST
119
URL Methods
/api/bookings GET, POST
/api/bookings/{id} GET, POST, PUT, DELETE
/api/hotels GET
/api/hotels/{id} GET
177. REpresentational State Transfer
REST
120
URI Template Contract
- Client is bound to honoring URI
structure (URIs change!)
- Exposing more detail about
implementation then necessary
- Domain-specific logic duplicated on
the client-side
183. REpresentational State Transfer
REST
126
Resource State
1. Information belonging to the resource
2. Links to related resources
3. Possible transition(s) to a future
state(s) of the resource
191. 4. Uniform Interface
REpresentational State Transfer
REST
133
Should we give
each representation
a media type?
192. 4. Uniform Interface
REpresentational State Transfer
REST
134
Media Types /
Representations
‣ Usually there is NO 1:1 relationship between media
type and representation
‣ Usually having one single monolithic media type is
too bulky
‣ One media type per application domain context is
usually OK
193. «A REST API should spend almost all of its
descriptive effort in defining the media
type(s) used for representing resources and
driving application state, or in defining
REpresentational State Transfer
REST
135
extended relation names and/or
hypertext-enabled mark-up for existing
standard media types.»
Roy T. Fielding, 2008
195. Hypermedia Factors / Link Support
<img src="/images/cities/lviv.jpg">
REpresentational State Transfer
REST
137
LE = Link Embedded
HTTP GET
196. Hypermedia Factors / Link Support
REpresentational State Transfer
REST
138
LO = Link Outbound
<a href="/pages/hotels/nobilis-lviv.html">
Nobilis Lviv
</a>
HTTP GET
197. Hypermedia Factors / Link Support
REpresentational State Transfer
REST
139
LT = Templated Queries
<form method="get" action="/hotels/search">
<input name="query" type="text">
<input type="submit">
</form>
HTTP GET
198. LN = Non-Idempotent Updates
REpresentational State Transfer
REST
140
Hypermedia Factors / Link Support
<form method="post" action="/bookings">
<input name="roomId" type="hidden" value="3">
<input name="from" type="text">
<input name="to" type="text">
<input type="submit">
</form>
HTTP POST
199. Hypermedia Factors / Link Support
REpresentational State Transfer
REST
141
LI = Idempotent Updates
new XmlHttpRequest().open("DELETE", "/bookings/3")
HTTP PUT, DELETE
200. Hypermedia Factors / Control Data Support
REpresentational State Transfer
REST
142
CR = Read Modification
<xsl:include href=«/newsfeed"
accept="application/rss" />
HTTP Accept-* headers
201. Hypermedia Factors / Control Data Support
<form method="post" action=«/bookings"
enctype="application/x-www-form-urlencoded">
<input name="roomId" type="hidden" value="3">
<input name="from" type="text">
<input name="to" type="text">
<input type="submit">
</form>
REpresentational State Transfer
REST
143
CU = Update Modification
HTTP Content-* headers
202. Hypermedia Factors / Control Data Support
<form method="post" action="/bookings">
<input name="roomId" type="hidden" value="3">
<input name="from" type="text">
<input name="to" type="text">
<input type="submit">
</form>
REpresentational State Transfer
REST
144
CM = Method Modification
HTTP GET/PUT/POST/…
203. Hypermedia Factors / Control Data Support
<link rel="stylesheet" src="styles.css" />
REpresentational State Transfer
REST
145
CL = Link Semantics
HTTP GET/PUT/POST/…
205. REpresentational State Transfer
REST
HTML XML JSON
LE ⩗ ⊗ ⊗
LO ⩗ ⊗ ⊗
LT ⩗ ⊗ ⊗
LN ⩗ ⊗ ⊗
LI ⊗ ⊗ ⊗
CR ⊗ ⊗ ⊗
CU ⩗ ⊗ ⊗
CM ⩗ ⊗ ⊗
CL ⩗ ⊗ ⊗
147
Hypermedia Factors
206. REpresentational State Transfer
REST
JSON-LD JSON API HAL Cj Siren Mason Uber
LE ⩗ ⩗ ⩗ ⩗ ⩗ ⩗ ⩗
LO ⩗ ⩗ ⩗ ⩗ ⩗ ⩗ ⩗
LT ⊗ ⩗ ⩗ ⩗ ⊗ ⩗ ⩗
LN ⊗ ⊗ ⊗ ⩗ ⩗ ⩗ ⩗
LI ⊗ ⊗ ⊗ ⩗ ⩗ ⩗ ⩗
CR ⊗ ⊗ ⩗ ⊗ ⩗ ⩗ ⩗
CU ⊗ ⊗ ⊗ ⊗ ⩗ ⩗ ⩗
CM ⊗ ⊗ ⊗ ⊗ ⩗ ⩗ ⩗
CL ⩗ ⩗ ⩗ ⩗ ⩗ ⩗ ⩗
148
JSON-based Media Types
207. REpresentational State Transfer
REST
149
HAL Overview
Hypertext Application Language:
• simple format
• explorable & discoverable APIs
• for JSON:
! application/vnd+json
• for XML:
application/vnd+xml
220. http://www.booking-rest.com/v1/bookings
REpresentational State Transfer
REST
159
1. Version in URI
• /v1/bookings/9111 != /v2/bookings/9111?
Not necessarily
• Should client support both /v1 and /v2?
Maintenance nightmare
• Should client start constructing URIs then?
Breaks HATEOAS
222. REpresentational State Transfer
REST
160
2. Version in Media Type
• Another representation of /bookings/9111?
Yes!
• Should client support both /v1 and /v2?
Client chooses which version to support
through «Accept»
• No need to construct URIs
HATEOAS preserved
223. application/vnd.booking.v2+json
application/vnd.booking+json; version=2.0
REpresentational State Transfer
REST
160
2. Version in Media Type
• Another representation of /bookings/9111?
Yes!
• Should client support both /v1 and /v2?
Client chooses which version to support
through «Accept»
• No need to construct URIs
HATEOAS preserved