REpresentational State Transfer

REST

REST
Theory and Practice

Vladimir Tsukur / Design Engineer & Team Lead @GlobalLogic, Partner @FrostDigital 2012

REST

REpresentational State Transfer 3

REST


REST

«A software architecture is an abstraction
of the run-time elements of a software
system during some phase of its operation»

Roy T. Fielding, 2000


REST

Architecture Elements

Components
Components
Components

Data

Connectors


REST

Architecture Elements

SQL

DAO DB


REST

«An architectural style is a coordinated set
of architectural constraints that restricts the
roles/features of architectural elements and
the allowed relationships among those
elements within any architecture that
conforms to that style»



REST

REST = style


REST

It is actually a hybrid style ;)


REST

WWW Requirements First

‣ Low Entry-barrier ‣ Hypermedia
‣ Extensibility ‣ Prepare for change
‣ Distributed Hypermedia ‣ Large-grain data transfer
‣ Internet-scale ‣ Anarphic scalability
‣ Independent deployment


REST

REST
Constraints


REST

1. Client - Server

+ Separation of concerns
+ UI portability
+ Improved scalability


REST

2. Stateless

+ Visibility - Performance
+ Reliability - Consistency
+ Scalability


REST

3. Cache

+ Efﬁciency - Reliability
+ Scalability
+ UP Performance


REST

Client-Cache -
Stateless-Server =

<
1994


REST

Web < 1994

- Static documents
- CERN libwww common library
- No consistent set of semantics
for all resources


REST

4. Uniform Interface

+ Simplicity - Efﬁciency
+ Visibility
+ Evolvability


REST

5. Layered System

+ Simplicity - UP Performance
+ Scalability
+ Evolvability


REST

6. [Code-on-Demand]

+ Client Simplicity - Visibility
+ Extensibility


REST

REST


REST

REST
Data Elements


REST

Resources


REST

Resources

<a href=’ ’>Winnie</a>


REST

«A resource is a conceptual mapping to a
set of entities, not the entity that
corresponds to the mapping at any
particular point in time.»



REST

Resources

=> {}
=> static:

=> dynamic:


REST

Resources

M R(t)={
ids and/or

representations

}


REST

Resources

1.0 1.1 2.0 «latest»


REST

Resources

1.0 1.1 2.0 != «latest»


REST

Resources

+ Generality
+ Late binding of reference to
implementation (request-time)
+ Allows to reference concept, not
some singular representation


REST

Resource IDs


REST

Resource IDs

http://www.teddybear.org/winnie


REST

Resource IDs
«Since centralized link servers are an
anathema to the immense scale and multi-
organizational domain requirements of the
Web, REST relies instead on the author
choosing a resource identifier that best fits
the nature of the concept being identified.»



REST

Resource Representations
Content-Type: text/plain
Thu Jul 05 2012 20:05:15 GMT+0300 (EEST)

Content-Type: text/xml
<current-time>1341095876929</current-time>


REST

Resource Representations

• Data
Thu Jul 05 2012 20:05:15 GMT+0300 (EEST)
• Metadata
• [Metadata to describe the
metadata]


REST

Metadata

• Name-Value Pairs
• Resource Metadata
Allow: GET, HEAD, OPTIONS

• Representation Metadata


REST

Control Data

• Deﬁnes purpose of the message
GET

• Used to parameterize request
(e.g. caching)
If-Modified-Since: Sat, 29 Oct 1994
19:43:31 GMT


REST

Media Types
• Data Format = Media Type
• Intention
• Automated processing
• Rendered / viewed by a user
• Both
• Composite Media Types
• Affects Latency

REST

Connectors
• Client
• Server
• Cache
• Shared (Akamai)
• Non-shared (browser)
• Resolver (DNS)
• Tunnel (SSL)

REST

Components

• Origin Server
• Gateway
• Proxy
• User Agent


REST

2
Practice


REST


REST

Booking Lifecycle
update cancel
Cancelled

create conﬁrmed
Pending Conﬁrmed
"live"

rejected Served

update

Rejected delete


REST

CRUD


REST

Create New Booking
POST /bookings HTTP/1.1
Host: www.booking-rest.com
Content-Type: application/json

{
«user-id»: «anonymous-developer»,
«hotel-id»: «paris:bergere-opera-hotel-3»,
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«room-type»: «standard-2x»,
«breakfast»: true
}


REST

Create New Booking

{
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«breakfast»: true
}

HTTP/1.1 201 Created
Location: http://www.booking-rest.com/bookings/9111

{
...
«state»: «PENDING»
}


REST

POST?


REST

POST?

• Server determines resource URI
• We are changing server state
(POST is not safe!)
• Resubmitting may create
another booking (POST is non-
idempotent!)


REST

Creation Failure - 400

{
...
«hotel-id»: «mars:escapism»,
...
}


REST


{
...
...
}

HTTP/1.1 400 Bad Request

{
«error»: «WTF is your hotel-id?»
}


REST


{
...
...
}

Modify request before resubmitting!!!


REST


{
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«breakfast»: true
}

HTTP/1.1 500 Internal Server Error

{
«error»: «donno what went wrong»
}


REST


{
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«breakfast»: true
}

throw new Exception(«donno
what went wrong»)


REST

• Forward progress is tricky
(booking created or not?)
• Retry
• Recompute state
• Try to be descriptive when
returning 500 or avoid if it is
possible

REST


{
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«breakfast»: true
}

HTTP/1.1 503 Service Unavailable
Retry-After: 60

{
«error»: «Have a headache right now. Please try
again in a minute»
}


REST

CRUD


REST

Reading Booking
GET /bookings/9111 HTTP/1.1

HTTP/1.1 200 OK

{
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«breakfast»: true
}


REST

GET?

• No side effects (GET is safe!)
• Resubmitting will return the
same result if resource haven’t
changed (GET is idempotent /
nullipotent!)


REST

Reading Booking (Later)

HTTP/1.1 200 OK

{
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«breakfast»: true
«state»: «SERVED»
}


REST

Reading Booking - 404

GET /bookings/mars HTTP/1.1

HTTP/1.1 404 Not Found


REST

CRUD


REST

Updating Booking
PUT /bookings/9111 HTTP/1.1

{
«from»: «2012-07-22»,
«to»: «2012-07-29»,
«breakfast»: true,
}

HTTP/1.1 200 OK

{
...
}


REST

PUT?


REST

PUT?

• Client determines resource URI
• We are changing server state
(PUT is not safe!)
• Resubmitting will result in the
same resource state (PUT is
idempotent!)


REST

Updating Booking - 204

{
«from»: «2012-07-22»,
«to»: «2012-07-29»,
}

HTTP/1.1 204 No Content


REST

PUT: 200 or 204?

• 200 more descriptive and
conﬁrms server-side state
• 204 is more efﬁcient


REST

Updating Booking - 409

{
«from»: «2012-07-22»,
«to»: «2012-07-29»,
}

HTTP/1.1 409 Conflict

{
...
}


REST

PUT or
POST
for Create/Update?


REST

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 computed by the client
sending full content of the specified
resource


REST

Partial / Bulk
Updates?


REST

Partial Update Strategies
1. Encapsulate «partial» into its own sub-resource
and invoke PUT on it
• ... only if this new resource makes sense to
others! Don’t do it just to avoid POST!
2. Use POST for resource or sub-resource
responding with «303 See Other» pointing to
parent resource (Fielding разрешает!)
3. Use PATCH (once universally deployed)


REST

Partial Update - POST
POST /bookings/9111/dates HTTP/1.1

{
«from»: «2012-07-22»,
«to»: «2012-07-29»
}

HTTP/1.1 303 See Other


HTTP/1.1 200 OK

...


REST

Partial Update - PUT

PUT /bookings/9111/from HTTP/1.1

2012-07-22

HTTP/1.1 200 OK

2012-07-22


REST

Bulk Update Strategies


REST

Bulk Update Strategies
1. HTTP Pipelining
1. Not well supported :(
2. Innappropriate for non-idempotent methods
like POST
2. Well, use POST, as «universal» method. Respond
with «303 See Other»
3. If you need to remove a set of sub-resources
and list is not very long, just issue DELETE
listing ids in the URL


REST

Bulk Update - POST

POST /bookings/cancelled HTTP/1.1

{
«ids»: [«9111», «9112», «9113», «9114»]
}

HTTP/1.1 303 See Other
Location: http://www.booking-rest.com/bookings


REST

CRUD


REST

DELETE Booking - 204

DELETE /bookings/9111 HTTP/1.1



REST


HTTP/1.1 200 OK

{
«from»: «2012-07-22»,
«to»: «2012-07-29»,
}


REST



HTTP/1.1 404 Not Found


REST

DELETE Disallowed - 405

DELETE /current-time HTTP/1.1
Host: www.time.com

HTTP/1.1 405 Method Not Allowed
Allow: GET


REST

Is it REST API?


REST

Is it REST API?
NO


REST

Richardson
Maturity
Model


REST

RMM


REST

Level 0 - Create
POST /bookingService HTTP/1.1

{
«create»: {
«from»: «2012-07-22»,
«to»: «2012-07-29»,
...
}
}
HTTP/1.1 200 OK

{
«id»: «9111»
}


REST

Level 0 - Retrieve

{
«retrieve»: {
«id»: «9111»
}
}

HTTP/1.1 200 OK

{
«from»: «2012-07-22»,
«to»: «2012-07-29»,
...
}


REST

Level 0 - Conﬁrm

{
«confirm»: {
«id»: «9111»,
«credit-card»: «1111-2222-3333-4444»,
...
}
}

HTTP/1.1 200 OK

{
«id»: «1234»
}


REST

Level 0


REST

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


REST

Level 0
1. Single URI endpoint
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

Level 1 - Create
POST /booking HTTP/1.1

{
«create»: {
«from»: «2012-07-22»,
«to»: «2012-07-29»,
...
}
}

HTTP/1.1 200 OK

{
«id»: «9111»
}


REST

Level 1 - Retrieve
POST /booking HTTP/1.1

{
«retrieve»: {
«id»: «9111»
}
}

HTTP/1.1 200 OK

{
«from»: «2012-07-22»,
«to»: «2012-07-29»,
...
}


REST

Level 1 - Conﬁrm
POST /confirmation HTTP/1.1

{
«create»: {
«id»: «9111»,
«credit-card»: «1111-2222-3333-4444»,
...
}
}

HTTP/1.1 200 OK

{
«id»: «1234»
}


REST

Level 1


REST

Level 1
1. Multiple resources
3. Action in URI or payload


REST

Level 1
1. Multiple resources
3. Action in URI or payload

Flickr «REST» API,
Amazon SimpleDB

REST

Level 2


REST

Level 2
1. Many URIs
2. Many verbs
3. We’ve designed it already ;)


REST

Level 2
1. Many URIs
2. Many verbs
3. We’ve designed it already ;)

Amazon S3
Twitter API
Google Calendar API

REST

Level 2 APIs
HTTP-based Type 1 HTTP-based Type 2

Identiﬁcation of Resources Yes Yes

Manipulation of Resources through
Yes Yes
Representations

Self-Descriptive Messages No Yes

HATEOAS No No

Examples Twitter API Google Calendar API


REST

Level 3?


REST

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



REST

HATEOAS


REST

Browsing

Follow links
Change application state
Move towards your goal


REST

Interaction

HTTP/1.1 200 OK

{
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«breakfast»: true
}


REST

Interaction

HTTP/1.1 200 OK

{
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«breakfast»: true
}

Exchange of resource state,
not application state

REST

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

{
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«breakfast»: true
}


REST

Domain Application Protocol
Legal interactions between consumer and a set
of resources involved in a business process

update cancel
Cancelled

create conﬁrmed
Pending Conﬁrmed
"live"

rejected Served

update

Rejected delete


REST

HTTP/1.1 200 OK

{
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«breakfast»: true
}


REST

HTTP/1.1 200 OK

{
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«breakfast»: true
}

What’s next?


REST

URI Templates

- Service is bound to honoring
these templates forever (and URIs
do change!)
- You’re exposing too much detail
about implementation


REST

Single entry-
point URI(s)


REST

Single entry-
point URI(s)
http://www.booking-rest.com/bookings


REST

Loose Coupling
Understanding of speciﬁc URI structure

‣ Change URI shapes
‣ Relocate resources to
different servers (partitioning)


REST

Loose Coupling

Semantics of a «link»!!!


REST

Loose Coupling

Semantics of a «link»!!!

«link» = hypermedia control


REST

Hypermedia Control
HTTP/1.1 200 OK

{
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«state»: «PENDING»,
«confirmation»: «http://www.booking-rest.com/confirmation/9111»
}


REST

Hypermedia Control
{
...
«confirmation»: «http://www.booking-rest.com/confirmation/9111»,
«cancellation»: «http://www.booking-rest.com/cancellation/9111»,
...
}


REST

Hypermedia Control
{
...
«confirmation»: «http://www.booking-rest.com/confirmation/9111»,
«cancellation»: «http://www.booking-rest.com/cancellation/9111»,
...
}

Elements have different protocol
semantics, but identical link semantics


REST

Better Hyperm Control
HTTP/1.1 200 OK

{
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«link»: {
«rel»: «confirmation»
«href»: «http://www.booking-rest.com/confirmation/9111»
}
}


REST

Media Type
HTTP/1.1 200 OK

{
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«link»: {
«rel»: «confirmation»,
}
}


REST

Media Type
HTTP/1.1 200 OK

{
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«link»: {
}
}

Should it be interpreted as plain vanilla JSON?


REST

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


REST

Media Type
HTTP/1.1 200 OK

{
...
«link»: {
}
}

Interpretative scheme for each format
includes hypermedia control deﬁnitions


REST

Media Type
HTTP/1.1 200 OK

{
...
«link»: {
}
}

Interpretative scheme for each format
includes hypermedia control deﬁnitions

JSON doesn’t deﬁne a «link»


REST

Better Media Type
HTTP/1.1 200 OK
Content-Type: application/vnd.booking+json

{
«from»: «2012-07-20»,
«to»: «2012-07-27»,
«link»: {
«rel»: «confirmation»
}
}


REST

Should we give
each representation
a media type?


REST

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


REST

Create New Booking HTTP/1.1 201 Created

{
...
«links»: [
{
«rel»: «confirm»,
«href»: «http://www.booking-rest.com/confirmation/9111»,
«mediaType»: «application/vnd.booking+json»
},
{
«rel»: «update»,
«href»: «http://www.booking-rest.com/orders/9111»,
},
{
«rel»: «cancel»,
«href»: «http://www.booking-rest.com/confirmation/9111»,
},
{
«rel»: «self»,
}
]
...
}


REST

«link»

‣ URI - identiﬁes 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 request payload


REST

Conﬁrm Booking
POST /confirmation/9111 HTTP/1.1

{
«card-number»: «1111-2222-3333-4444»,
«cvc»: «987»,
«amount»: «1000.00»
}
HTTP/1.1 200 OK
Location: /confirmation/9111/1234

{
...
«links»: [
{
«rel»: «receipt»,
},
{
«rel»: «order»,
}
]
...
}


REST

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



REST

«... It has value because it is far easier to
standardize representation and relation
types than it is to standardize objects
and object-speciﬁc interfaces ...»



REST

Versioning


REST

1. Version in URI


REST

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


REST

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

• /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

2. Version in Media Type


REST


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


REST

application/vnd.booking.v2+json
application/vnd.booking+json; version=2.0

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


REST

3. Version in Header


REST


X-REST-API-Version: 2.0


REST


X-REST-API-Version: 2.0

Also ﬁne but can be ﬁltered out by
proxies or intermediaries


REST

Transactions


REST

Transactions
1. If you need transactions, treat them as
corresponding resources
1. Create transaction as POST
2. Fill it with data and initiate by issuing PUT
2. There is no concept of «distributed transaction»
in REST. Treat «distributed» nature of the
transaction as implementation detail


REST

Transaction
POST /transfer HTTP/1.1
Host: www.money-rest.com

HTTP/1.1 201 Created
Location: http://www.money-rest.com/transfer/9111

PUT /transfer/9111 HTTP/1.1
Host: www.money-rest.com

{
«from»: «husband»,
«to»: «wife»,
«amount»: «1000.00»,
«amount»: «UAH»,
«description»: «fitness»
}



REST

Frameworks
(Java)


REST

Thanks!
Questions?

121

REpresentational State Transfer

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Was ist angesagt?

Was ist angesagt? (20)

Ähnlich wie REpresentational State Transfer

Ähnlich wie REpresentational State Transfer (19)

Mehr von Vladimir Tsukur

Mehr von Vladimir Tsukur (11)

Kürzlich hochgeladen

Kürzlich hochgeladen (20)

REpresentational State Transfer

Hinweis der Redaktion