RESTful Title for Technical Document

Vladimir Tsukur / Design Engineer & Team Lead @GlobalLogic, Partner @Easyhunt / Frost Digital
REST
2014
Take a REST!
Theory and Practice

REpresentational State Transfer
REST
2
team &
tech lead @
vladimir tsukur partner @

REST
3
architectural elements
CCCooommmpppooonnneenentntssts
Connectors
Data

REST
GET /hist
…
4
cat http.log | grep GET
GET /hist
PUT /doc/1
…
cat http.log grep GET
stdout stdin
stdout
∅

«An architectural style is a … set of
CONSTRAINTS that restricts the roles of
REST
5
architectural elements …»
Roy T. Fielding, 2000

REST
REST
is a style for
WEB
6

REpresentational
REST
7
State
Transfer

REST
8

REST
9

REST
10

REST
11
REST ?
style ?

REST
12
«Be of the web,
not behind the web»
Ian Robinson

REST
13
WWW Requirements
• Low Entry-barrier
• Extensibility
• Distributed Hypermedia
• Internet-scale
✓Hypermedia
✓Prepare for change
✓Large-grain data transfer
✓Anarchic scalability
✓Independent deployment

REST
14
REST
Constraints

REST
15
1. Client - Server
2. Stateless Server
3. Cache
4. Uniform Interface
5. Layered System
6. [Code-on-Demand]

REST
16
1. Client - Server

REST
17
1. Client - Server
POST /hotels/lviv/nobilis/suite-room/booking
…
!
{
«from»: «2014-09-10»,
«to»: «2012-09-20»,
«breakfast»: true
}
request

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

REST
18
1. Client - Server
Separation of Concerns:
!
• Client responsible for UI
• Server responsible for data storage

REST
19
1. Client - Server

REST
19
1. Client - Server
+ Scalability
+ Simplicity
+ Evolvability

REST
20
2. Stateless Server

REST
21
Two Types of State
• Application State
!• Resource State

REST
22
Application State
Where you ARE in the
interaction / session
Pending Confirmed
Served
create
update
rejected
cancel Cancelled
"live"
confirmed
Rejected
update
delete

REST
23
Resource State
What is stored on the server
(beyond session)

REST
24
2. Stateless Server
• Each request contains ALL the
information necessary to understand it
!
• Application (session) state is kept on
the client

REST
25
2. Stateless Server

REST
25
2. Stateless Server
GET /hotels?page request
{
«hotels»: <1..25>,
«_links»: {
«next»: «/hotels?page=2»
}
}
response

GET /hotels?page=2 request
REST
25
2. Stateless Server
GET /hotels?page request
{
«hotels»: <1..25>,
«_links»: {
}
}
response
{
«hotels»: <26..50>,
«_links»: {
«previous»: «/hotels?page=1»,
}
}
response
⚡

REST
26
2. Stateful Server

REST
26
2. Stateful Server
POST /session request
response Set-Cookie: JSESSIONID=987

GET /hotels
Cookie: JSESSIONID=987 request
REST
26
2. Stateful Server
{
«hotels»: <1..25>
} response

GET /hotels
GET /hotels/next
REST
26
2. Stateful Server
{
«hotels»: <1..25>
} response
{
«hotels»: <26..50>
} response

REST
27

REST
28
Use Cookies for
Application State?
ain’t RESTful, sorry!

REST
29
2. Stateless Server

REST
29
2. Stateless Server
+ Visibility
+ Reliability
+ Scalability

REST
29
2. Stateless Server
+ Visibility
+ Reliability
+ Scalability
- Performance
- Consistency

REST
30
3. Cache

REST
31
3. Cache
• Acts as a mediator between client &
server potentially reusing responses to
equivalent requests

REST
32
3. Cache

REST
32
3. Cache
GET /hotels request
200 OK
Cache-Control: max-age=3600, must-revalidate
!
{
«hotels»: <1..25>,
…
}
response

REST
32
3. Cache
GET /hotels request
200 OK
!
{
«hotels»: <1..25>,
…
}
response
request
cache
GET /hotels
200 OK
!
{
«hotels»: <1..25>,
…
}

REST
33
3. Cache

REST
33
3. Cache
+ Efficiency
+ Scalability
+ UP Performance

REST
33
3. Cache
+ Efficiency
+ Scalability
+ UP Performance
- Reliability

REST
34
Client-Cache -
Stateless-Server =
Web < 1994

REST
35
Web < 1994
- Static documents
- CERN libwww common library
- No consistent set of semantics
for all resources

REST
36

REST
37

REST
38
1. Identification of resources
2. Manipulation of resources through
representations
3. Self-descriptive messages
4. HATEOAS

REST
39
Resource
is a key abstraction

REST
40
/images/beautiful-lviv.jpg

REST
41
/images/beautiful-kyiv.jpg

REST
42
/documents/folder/profile.doc

REST
43
/time/current

REST
44
/api/hotels/lviv

REST
45
/api/hotels/lviv/nobilis

REST
46
/api/hotels/lviv/nobilis/classic

REST
47
/abstraction

REST
48
resource => entity
!
entity ≠> resource

Resources
REST
49
/v1

Resources
REST
49
/v1 /v2

REST
49
/v1
/latest
/v2
Resources

REST
49
/v1
/v2 /v3
/latest
Resources

Resources
REST
49
/v1
/v2 /v3
/latest
/v2 != /latest
/v3 != /latest

Resources
REST
50
=> {}
=> static:
!
=> dynamic:

Resources
REST
51
+ Generality
+ Allows late binding
+ Allows to reference
concept, not singular
representation

REST
52
4.1. Identification of Resources

4.1. Identification of Resources
REST
53
http://www.google.com
ftp://user:password@host:port/path
urn:ISBN:0-395-36341-1

REST
54
4.2. Manipulation of Resources
through Representations

Content Negotiation = Conneg
REST
55
GET /current-time
Accept: text/plain request

Content Negotiation = Conneg
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

Conneg
REST
56
GET /current-time
Accept: text/xml request

Conneg
REST
56
GET /current-time
Accept: text/xml request
200 OK
Content-Type: text/xml
!
<current-time>1341095876929</current-time>
response

REST
57
GET /current-time
Accept: text/plain;q=0.8,
text/xml;q=0.9
request
Conneg

Conneg
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

REST
58
Representation Structure
200 OK
Content-Length: 41
!
Thu Aug 30 2014 09:30:15 GMT+0300 (EEST)

Metadata
REST
58
200 OK
Content-Length: 41
!
Thu Aug 30 2014 09:30:15 GMT+0300 (EEST)

Metadata
REST
58
200 OK
Content-Length: 41
!
Thu Aug 30 2014 09:30:15 GMT+0300 (EEST)
Data

REST
59
Content-Type drives
processing of the payload,
NOT the payload itself

• = Data Format
• Intention:
• Automated processing (JSON, XML)
• Rendered / viewed by a user (HTML)
• Both
• Composite Media Types
• Affects Latency
REST
60
Media Types (Content-Type)

Control Data
• Defines purpose of the message
GET
REST
61
• Used to parameterize request
(e.g. caching)
If-Modified-Since: Sat, 29 Oct 1994
19:43:31 GMT

REST
62
safe idempotent cacheable

REST
62
GET

REST
62
GET ⩗

REST
62
GET ⩗ ⩗

REST
62
GET ⩗ ⩗ ⩗

REST
62
GET ⩗ ⩗ ⩗
POST

REST
62
GET ⩗ ⩗ ⩗
POST ⊗

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗
PUT

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗
PUT ⊗

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗
PUT ⊗ ⩗

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗
PUT ⊗ ⩗ ⊗

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗
PUT ⊗ ⩗ ⊗
PATCH

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗
PUT ⊗ ⩗ ⊗
PATCH ⊗

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗
PUT ⊗ ⩗ ⊗
PATCH ⊗ ⊗

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗
PUT ⊗ ⩗ ⊗
PATCH ⊗ ⊗ ⩗

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗
PUT ⊗ ⩗ ⊗
PATCH ⊗ ⊗ ⩗
DELETE

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗
PUT ⊗ ⩗ ⊗
PATCH ⊗ ⊗ ⩗
DELETE ⊗

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗
PUT ⊗ ⩗ ⊗
PATCH ⊗ ⊗ ⩗
DELETE ⊗ ⩗

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗
PUT ⊗ ⩗ ⊗
PATCH ⊗ ⊗ ⩗
DELETE ⊗ ⩗ ⊗

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗
PUT ⊗ ⩗ ⊗
PATCH ⊗ ⊗ ⩗
DELETE ⊗ ⩗ ⊗
HEAD

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗
PUT ⊗ ⩗ ⊗
PATCH ⊗ ⊗ ⩗
DELETE ⊗ ⩗ ⊗
HEAD ⩗

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗
PUT ⊗ ⩗ ⊗
PATCH ⊗ ⊗ ⩗
DELETE ⊗ ⩗ ⊗
HEAD ⩗ ⩗

REST
62
GET ⩗ ⩗ ⩗
POST ⊗ ⊗ ⩗
PUT ⊗ ⩗ ⊗
PATCH ⊗ ⊗ ⩗
DELETE ⊗ ⩗ ⊗
HEAD ⩗ ⩗ ⩗

REST
63
GET,PUT,POST,
DELETE
≠
!
CRUD

REST
64
REST ≠ CRUD
• CRUD represent operations on data
• CRUD pushes business logic to caller

REST
65
PUT or
POST
for Create/Update?

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

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»,
«data»: …
}
response

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

4.3. Self-descriptive messages
REST
69
Each message includes enough
information to describe how to process
the message
200 OK
Content-Type: application/json
!
{
«hotels»: <1..25>,
…
}

4.4. HATEOAS
REST
70
Application state transitions fully
driven by hypermedia

REST
71

REST
71
+ Simplicity
+ Visibility
+ Evolvability

REST
71
+ Simplicity
+ Visibility
+ Evolvability
- Efficiency

REST
72
5. Layered System

5. Layered System
REST
73
Each component does not «see»
beyond the immediate layer
!
Intermediaries:
• Proxies
• Gateways

REST
74
5. Layered System

REST
74
5. Layered System
+ Simplicity
+ Scalability
+ Evolvability

REST
74
5. Layered System
+ Simplicity
+ Scalability
+ Evolvability
- UP Performance

REST
75
6. [Code-on-Demand]

REST
76
6. [Code-on-Demand]
<!doctype html>
<html lang="en">
<head>
…
<script src="path/to/script.js"></script>
</head>
…
</html>

REST
77
6. [Code-on-Demand]
<!doctype html>
<html lang="en">
<head>
…
<applet width="200" height="200"
archive="applet.jar"
code="com.example.MainClass" />
</head>
…
</html>

REST
78
6. [Code-on-Demand]

REST
78
6. [Code-on-Demand]
+ Client Simplicity
+ Extensibility

REST
78
6. [Code-on-Demand]
+ Client Simplicity
+ Extensibility - Visibility

REST
79
6. [Code-on-Demand]
vs

REST
79
6. [Code-on-Demand]
vs
+ Simplicity
+ Visibility
+ UP Performance

REST
80
REST

REST
81
profit
+ Performance
+ Scalability
+ Simplicity
+ Evolvability
+ Visibility
+ Portability
…

REST
82
Default REST Impl
• HTTP (RFC 2616,
RFC 7230-7235)
• URI (RFC 3986)
• HTML

REST
83
Richardson
Maturity
Model

REST
84
RMM

REST
85
Level 0 - Book
POST /bookings
{
«createBooking»: {
«data»: {
«from»: «2014-09-10»,
«to»: «2012-09-20»,
«breakfast»: true
}
}
}
request
200 OK
{
«success»: {
«id»: «123»,
«data»: …
}
}
response

REST
86
Level 0 - Get Booking
POST /bookings
{
«getBooking»: {
«id»: «123»
}
}
request
200 OK
{
«success»: {
«id»: «123»,
«data»: …
}
}
response

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

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»,
«data»: …
}
}
response

REST
89
POST /bookings/123
{
«getBooking»: {
«id»: «123»
}
}
request
200 OK
{
«success»: {
«id»: «123»,
«data»: …
}
}
response

REST
90
Level 1
1. Multiple resources
2. Single HTTP method
3. Action in URI or payload
Flickr «REST» API,
Amazon SimpleDB

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»,
«data»: …
}
response

REST
92
GET /bookings/123
request
200 OK
{
«id»: «123»,
«data»: …
}
response

REST
93
Level 2
1. Many URIs
2. Many verbs
3. But NO hypermedia
Amazon S3
Twitter API
Google Calendar API

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

REST
95
Level 3?

REST
96
2
Hypermedia &
Media Types

REST
97

«If the engine of application state (and
hence the API) is not being driven by
hypertext, then it cannot be RESTful and
REST
98
cannot be a REST API. Period.»

REST
99
HATEOAS

REST
100
Browsing
Follow links
Change application state
Move towards your goal

REST
101
Take a REST
https://github.com/flushdia/take-a-REST

{
«take-a-rest:hotel»: {
«href»: «http://localhost:8080/api/hotels/2»,
«mediaType»: «application/hal+json»
}
}
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

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

REST
104
Application Lifecycle

REST
105
Booking Lifecycle

REST
106

REST
107
CREATED Booking
Initial Transitions

REST
108
CREATED Booking
payment N/A - to be paid on the spot
N/A

if (booking.links.has(«payment»)) {
// draw payment button / UI
}
REST
109
Client

REST
110
HATEOAS client
does NOT break,
because it does NOT
expect link to be
always available

REST
111
CREATED Booking
service link added - new functionality
N/A

REST
112
Upgraded / new client
MAY leverage new
features when updated.
!
Existing clients stay intact

REST
113
Client may know
HOW,
but
NOT WHEN

«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
REST
114
control-oriented integration.»

«... It has value because it is far easier to
standardize representation and relation
types than it is to standardize objects
and object-specific interfaces ...»
REST
115

REST
116
profit
• API: explorable & self-documented
• Client:
• No URL construction
• No domain logic replication
• Less coupling
• Server:
• Transparent resource relocation
• Easier versioning & evolvability

REST
117
Is somebody
hypermedia-ing?

REST
118

URI Template Contract
REST
119
URL Methods
/api/bookings GET, POST
/api/bookings/{id} GET, POST, PUT, DELETE
/api/hotels GET
/api/hotels/{id} GET

NOT HATEOAS
REST
119
URL Methods
/api/bookings GET, POST
/api/bookings/{id} GET, POST, PUT, DELETE
/api/hotels GET
/api/hotels/{id} GET

REST
120
- Client is bound to honoring URI
structure (URIs change!)
- Exposing more detail about
implementation then necessary
- Domain-specific logic duplicated on
the client-side

REST
121
REST
does NOT care
about URI values
/whatever/is/fine/
to/be/restful

REST
122
Single entry-point
URI(s) *
/api
* (or a limited set of URIs)

REST
123
Other stuff
discovered via
links

REST
124
Extras!

REST
125
Resource State

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

REST
127
Resource State
1. Info belonging to resource

REST
128
Resource State
2. Links to related resources

REST
129
Resource State
3. Possible state transitions

REST
130
Media Type
HTTP/1.1 200 OK
…
!
{
«_links»: …,
«_embedded»: …,
«city»: "Kyiv",
«from»: [ 2014, 10, 1 ],
«to»: [ 2014, 10, 15 ],
«hotel»: "Premier Palace",
«includeBreakfast»: false,
«paid»: true,
«price»: 1000,
«roomType»: "ROOM"
}

HTTP/1.1 200 OK
…
!
{
«_links»: …,
«_embedded»: …,
«city»: "Kyiv",
«from»: [ 2014, 10, 1 ],
«to»: [ 2014, 10, 15 ],
«paid»: true,
«price»: 1000,
}
REST
130
Media Type
Should it be interpreted as plain vanilla JSON?

REST
131
Better Media Type
HTTP/1.1 200 OK
Content-Type: application/vnd.take-a-rest.booking+json
…
!
{
«_links»: …,
«_embedded»: …,
«city»: "Kyiv",
«from»: [ 2014, 10, 1 ],
«to»: [ 2014, 10, 15 ],
«paid»: true,
«price»: 1000,
}

REST
132
Media Type Profile
HTTP/1.1 200 OK
Content-Type: application/hal+json; profile=take-a-rest:booking
…
!
{
«_links»: …,
«_embedded»: …,
«city»: "Kyiv",
«from»: [ 2014, 10, 1 ],
«to»: [ 2014, 10, 15 ],
«paid»: true,
«price»: 1000,
}

REST
133
Should we give
each representation
a media type?

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

«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
REST
135
extended relation names and/or
hypertext-enabled mark-up for existing
standard media types.»

REST
136
Hypermedia Factors
Measurement of the level
of hypermedia support

Hypermedia Factors / Link Support
<img src="/images/cities/lviv.jpg">
REST
137
LE = Link Embedded
HTTP GET

REST
138
LO = Link Outbound
<a href="/pages/hotels/nobilis-lviv.html">
Nobilis Lviv
</a>
HTTP GET

REST
139
LT = Templated Queries
<form method="get" action="/hotels/search">
<input name="query" type="text">
<input type="submit">
</form>
HTTP GET

LN = Non-Idempotent Updates
REST
140
<form method="post" action="/bookings">
<input name="roomId" type="hidden" value="3">
<input name="from" type="text">
<input name="to" type="text">
</form>
HTTP POST

REST
141
LI = Idempotent Updates
new XmlHttpRequest().open("DELETE", "/bookings/3")
HTTP PUT, DELETE

Hypermedia Factors / Control Data Support
REST
142
CR = Read Modification
<xsl:include href=«/newsfeed"
accept="application/rss" />
HTTP Accept-* headers

<form method="post" action=«/bookings"
enctype="application/x-www-form-urlencoded">
</form>
REST
143
CU = Update Modification
HTTP Content-* headers

<form method="post" action="/bookings">
</form>
REST
144
CM = Method Modification
HTTP GET/PUT/POST/…

REST
146
Hypermedia Factors
What about and ?

REST
HTML XML JSON
LE ⩗ ⊗ ⊗
LO ⩗ ⊗ ⊗
LT ⩗ ⊗ ⊗
LN ⩗ ⊗ ⊗
LI ⊗ ⊗ ⊗
CR ⊗ ⊗ ⊗
CU ⩗ ⊗ ⊗
CM ⩗ ⊗ ⊗
CL ⩗ ⊗ ⊗
147
Hypermedia Factors

REST
JSON-LD JSON API HAL Cj Siren Mason Uber
LE ⩗ ⩗ ⩗ ⩗ ⩗ ⩗ ⩗
LO ⩗ ⩗ ⩗ ⩗ ⩗ ⩗ ⩗
LT ⊗ ⩗ ⩗ ⩗ ⊗ ⩗ ⩗
LN ⊗ ⊗ ⊗ ⩗ ⩗ ⩗ ⩗
LI ⊗ ⊗ ⊗ ⩗ ⩗ ⩗ ⩗
CR ⊗ ⊗ ⩗ ⊗ ⩗ ⩗ ⩗
CU ⊗ ⊗ ⊗ ⊗ ⩗ ⩗ ⩗
CM ⊗ ⊗ ⊗ ⊗ ⩗ ⩗ ⩗
CL ⩗ ⩗ ⩗ ⩗ ⩗ ⩗ ⩗
148
JSON-based Media Types

REST
149
HAL Overview
Hypertext Application Language:
• simple format
• explorable & discoverable APIs
• for JSON:
! application/vnd+json
• for XML:
application/vnd+xml

REST
150
HAL

REST
151
HAL - state

REST
152
HAL - links

HAL - embedded resources
REST
153

REST
154
HAL

REST
155
HAL - CURies

REST
155
HAL - CURies
• Resource documentation
• Link name-spacing

REST
156
HAL Language Support
• Java
• Spring HATEOAS
• halbuilder-java
• halarious
• HyperExpress-HAL
• JavaScript
• Scala, Clojure, Ruby, Python, PHP, Objective
C, C#, Eiffel, Go, Rust, …

REST
157
HAL APIs

REST
158
Versioning

REST
159
1. Version in URI

REST
159
1. Version in URI
http://www.booking-rest.com/v1/bookings

http://www.booking-rest.com/v1/bookings
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

REST
160
2. Version in Media Type

REST
160
• Another representation of /bookings/9111?
Yes!
Client chooses which version to support
through «Accept»
• No need to construct URIs
HATEOAS preserved

application/vnd.booking.v2+json
application/vnd.booking+json; version=2.0
REST
160
• Another representation of /bookings/9111?
Yes!
Client chooses which version to support
through «Accept»
• No need to construct URIs
HATEOAS preserved

REST
161
3. Version in Header

REST
161
X-REST-API-Version: 2.0

REST
161
X-REST-API-Version: 2.0
Can be filtered out by proxies or
intermediaries

REST
162
4. Best Advice
DO NOT VERSION!

REST
162
4. Best Advice
DO NOT VERSION!
Support backwards compatibility,
enable discovery

REST
163
API Survey
March 2014
180+ respondents

Security Usability Can't decide
REST
164
API Survey - Top Priority
18 %
38 %
44 %

JSON XML Other
REST
165
API Survey - Format
2 %
48 % 51 %

SOAP CRUD Hypermedia
REST
166
API Survey - Style (Now)
24 %
39 %
38 %

28 %
21 %
14 %
7 %
REST
167
API Survey - Plans to add
0 %
Hypermedia SOAP CRUD

References - REST Core
• http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
• https://groups.yahoo.com/neo/groups/rest-discuss/conversations/topics/6735
• http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
• http://www.infoq.com/presentations/The-Counterintuitive-Web
• http://ruben.verborgh.org/blog/2012/08/24/rest-wheres-my-state/
• https://code.google.com/p/implementing-rest/wiki/Video
• http://channel9.msdn.com/posts/TechTalk-RESTful-Application-Protocols-From-Design-to-
REST
168
Implementation
• http://www.infoq.com/presentations/qcon-tilkov-rest-intro
• http://www.infoq.com/presentations/vinoski-rest-serendipity
• http://bitworking.org/news/373/An-Introduction-to-REST
• http://vimeo.com/15697358
• http://www.infoq.com/presentations/vinoski-rpc-convenient-but-flawed
• https://www.youtube.com/watch?v=llpr5924N7E
• https://www.youtube.com/watch?v=8Q7GyIBrysA
• http://steve.vinoski.net/pdf/IEEE-Demystifying_RESTful_Data_Coupling.pdf
• http://www.crummy.com/writing/speaking/2008-QCon/act3.html
• http://martinfowler.com/articles/richardsonMaturityModel.html

References - HTTP & URI
• https://www.mnot.net/blog/2014/06/07/rfc2616_is_dead
• http://www.ietf.org/rfc/rfc2616.txt
• http://tools.ietf.org/html/rfc7230
• https://www.mnot.net/blog/2013/05/15/http_problem
• https://www.mnot.net/blog/2012/12/04/api-evolution
• https://www.mnot.net/blog/2012/09/05/patch
• https://www.mnot.net/blog/2012/06/25/http_api_complexity_model
• https://www.mnot.net/blog/2012/04/17/profiles
• https://www.mnot.net/blog/2009/02/18/x-
• https://tools.ietf.org/html/rfc5789
REST
169

References -
Hypermedia & APIs
• https://www.mnot.net/blog/2013/06/23/linking_apis
• http://oredev.org/2010/sessions/hypermedia-apis
• http://vimeo.com/75106815
• https://www.innoq.com/blog/st/2012/06/hypermedia-benefits-for-m2m-communication/
• http://ws-rest.org/2014/sites/default/files/wsrest2014_submission_12.pdf
• http://www.infoq.com/news/2014/03/ca-api-survey
• https://twitter.com/hypermediaapis
• https://www.youtube.com/watch?v=hdSrT4yjS1g
• https://www.youtube.com/watch?v=mZ8_QgJ5mbs
• http://nordsc.com/ext/classification_of_http_based_apis.html
• http://soabits.blogspot.no/2013/12/selling-benefits-of-hypermedia.html
• https://github.com/mamund/Building-Hypermedia-APIs
• http://amundsen.com/hypermedia/hfactor/
• http://tech.blog.box.com/2013/04/get-developer-hugs-with-rich-error-handling-in-your-api/
REST
170

References - Media Types
• http://stateless.co/hal_specification.html
• https://github.com/kevinswiber/siren
• https://github.com/JornWildt/Mason
• http://json-ld.org/
• http://amundsen.com/media-types/collection/
• http://soabits.blogspot.com/2013/12/media-types-for-apis.html
• http://soabits.blogspot.no/2013/05/the-role-of-media-types-in-restful-web.
REST
171
html
• http://soabits.blogspot.com/2014/03/modelling-shipment-example-as.
html
• http://soabits.blogspot.com/2014/02/representing-issue-tracker-with-mason.
html
• https://github.com/mamund/media-types/blob/master/uber-hypermedia.
asciidoc

References - Versioning
• https://www.mnot.net/blog/2012/12/04/api-evolution
• https://www.mnot.net/blog/2012/07/11/header_versioning
• https://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown
• http://www.infoq.com/news/2013/12/api-versioning
• http://www.infoq.com/articles/Web-Service-Contracts
• http://www.infoq.com/news/2013/09/versioning-restful-services
• http://www.infoq.com/news/2010/06/rest-versioning
• http://www.ebpml.org/blog2/index.php/2013/11/25/understanding-the-costs-
REST
172
of-versioning
• http://www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.
html
• http://www.infoq.com/articles/contract-versioning-comp2

REST
173
References - Caching
• https://www.mnot.net/cache_docs/
• https://www.mnot.net/blog/2007/05/15/expires_max-age
• https://devcenter.heroku.com/articles/increasing-application-performance-
with-http-cache-headers
• https://devcenter.heroku.com/articles/jax-rs-http-caching

REST
174
References -
Tutorials & Tools
• https://jax-rs-spec.java.net/
• http://www.oracle.com/technetwork/articles/java/jaxrs20-1929352.html
• http://resteasy.jboss.org/
• https://code.google.com/p/siren4j/
• http://gotohal.net/
• https://www.youtube.com/watch?v=1wEp9yHHtwg
• https://www.youtube.com/watch?v=sVvL12BnIyQ
• https://www.youtube.com/watch?v=pCnXy2Hs2Ag
• https://www.youtube.com/watch?v=_0kmqtWYvaY
• http://kingsfleet.blogspot.com/2014/02/transparent-patch-support-in-jax-rs-20.html
• http://spring.io/guides/tutorials/rest/
• https://jaxb.java.net/
• https://github.com/FasterXML/jackson

REST
175
Thanks!
Questions?

RESTful Title for Technical Document

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

En vedette

En vedette (20)

Similaire à RESTful Title for Technical Document

Similaire à RESTful Title for Technical Document (20)

Plus de Vladimir Tsukur

Plus de Vladimir Tsukur (10)

Dernier

Dernier (20)

RESTful Title for Technical Document