ReST

by Nader Albert

Introduction To ReST

What is ReST? History of ReST Key General Concepts Key ReST Principles ReST Maturity Model Caching General Tips Key Issues and Challenges

Agenda

Representational State Transfer.

Transferring the State of a Resource in a Specific Representation.

ReST is an Architectural Style.

Client – Server Architecture.

Leveraging the application protocol capabilities of HTTP.

What is ReST?

Architectural Styles and the Design of Network-based Software Architectures, doctoral dissertation by Roy Fielding.

Inspired by the architecture of the World Wide Web

HTTP misconceived as a Transport Protocol, while it is not just that.

Leveraging HTTP capabilities gives straightforward application-to-application connectivity with very little effort.

History

Key Concepts• Resource Oriented Architecture• Server and Client Decoupled • Resource Representation

Resource Based instead of Action Based

Things instead of Actions

Nouns instead of Verbs

Resource Oriented Architecture (ROA)

ROA Decoupling Resource Representation

Server and Client Decoupled


Separate the Resource from its Representation

Resource has one structure and mult iple representations

Resource can be represented in different formats

Resource Representation


State

Structure

Format

Key ReST Principles• Unique Identifier• Link Things together• Use Standard Methods• Multiple Representations• Communicate Statelessly

Use URIs to identify everything that merits being identifiable.

Give Everything an Identifier

Unique Identifier Link Together Standard Methods Multiple Representations Stateless

http://example.com/customers/1234

http://example.com/orders/2007/10/776

http://example.com/products/4454

http://example.com/processes/salary-inc

http://example.com/customers/?orders=3

http://example.com/orders/2007/11

http://example.com/products?color=green

http://example.com/processes/

One thingCollections of

things

http://example.com/customers/1234

http://example.com/orders/2007/10/776

http://example.com/products/4454

http://example.com/processes/salary-inc







http://example.com/processes/

Link Things Together


<order xmlns=″http://schemas.restbucks.com″><location>takeAway</location><item>

<name>latte</name><quantity>1</quantity><milk>whole</milk><size>small</size>

</item><cost>2.0</cost><status>payment-expected</status>

<link rel=″http://restbucks.com/payment″ ref=″https://restbucks.com/payment/1 /><link rel=″http://restbucks.com/customer″

ref=″https://restbucks.com/customer/12 /></order>

Order

Customer

Item

Payment

Item

Use Standard Methods


Isolate Representation from Structure

Separation of concerns (framework understands format, application understands semantics)

Resource with Multiple Representations


GET / order/1234 HTTP /1.1Host: restbucks.comAccept: app l i ca t i on / j son

HTTP/1.1 200 OKContent-Length: 260Content-Type: app l i ca t i on / j son

XML,HTML,TEXT,CSV, JSON

Client requests a format

Server supplies the

format

XML,HTML,TEXT,CSV, JSON

Server doesn’t retain state for any client beyond a single request

Request encapsulates all necessary information

Number of clients impacts the server’s footprint if it keeps client state

Client doesn’t have to talk to the same server in two consecutive requests

Communicate Stateless


ReST Maturity Model• RestBucks Example• Richardson’ Maturity Model• POX Services• URI Tunnelling• CRUD Web Services• Hypermedia Web Services

RestBucks Example

Richardson Maturity Model

POX WEB SERVICES

Level 0

N o t Ye t T h e r e !

POX Services

Level Zero

Plain Old XML over HTTP.

Uses HTTP requests and responses to transfer documents between a client and a server.

Uses HTTP POST to transfer XML documents between systems.

Uses the URI, as an ident ifi er to a remote method

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

POX Services

Application semantics reside inside the XML payload while HTTP metadata is ignored.

Would work just as well over TCP connection.

Platform independence, and ubiquitous connectivity between systems.

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

POX Services

http://restbucks.com/placeOrder

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

Method Invocati

onOrder

Information, embedded in

the XML payload



XML-RPC Web Services

Falls under the POX umbrella.

An attempt to standardize the way in which information is represented in the HTTP request and response payloads.

Level Zero

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

XML-RPC Web Services

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

<method-call><method-name>PlaceOrder</method-name><params>

<param> <value> <string>1234</string> </value> </param>

<param> <array> <struct><member>

<name>Name</name><value><string>latte</string></value>

</member><member>

<name>Quantity</name><value><int>1</int></value>

</member> </struct> </array> </param> </params> </method-call>

SOAP Web Services

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

POST /InStock HTTP/1.1Host: www.example.orgContent-Type: application/soap+xml; charset=utf-8Content-Length: nnn

<soap:Envelopexmlns:soap="http://www.w3.org/2001/12/soap-envelope"soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Body xmlns:m="http://www.example.org/stock"><m:GetStockPrice> <m:StockName>XYZ</m:StockName>

</m:GetStockPrice></soap:Body>

</soap:Envelope>

URI TUNNEL SERVICES

Level 1

W e A r e H e r e !

URI Tunnelling

Level 1

HTTP only used as a transport protocol to move URI’s across the network.

Uses URIs to transfer information across system boundaries by encoding information within the URI itself.

The content of a URI, defines the piece of code to be executed and parameterizes it.

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

Order Information,

embedded in the URI

URI Tunnelling URIs are used to encode operations rather than

identify resources.

Tempting to violate the safe / idempotency rules.

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

CRUD WEB SERVICES

Level 2

W e A r e H e r e !

CRUD Web services

Level Two

Embrace HTTP as an application protocol.

Use URI’s to identify resources rather than methods.

Embrace HTTP (verbs , codes and Media Types).

Supports basic operations (create, read, update, delete)

Client retrieves Resource, investigates Media Type to decode Body

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

HTTP Verbs Service Contract is simple, concise, and

intuitive.

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

HTTP Status Codes2xx Success

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

3xx Redirection

4xx Client Error 5xx Server Error

http://www.restapitutorial.com/httpstatuscodes.html










HTTP Request / Response

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

CRUD Web services POST is used as a request to create a resource.

Payload contains a representation of the resource.

Create Read

Update Delete

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

201 Created (Request has been accepted)

CRUD Web services

Create Order ResponseCreate Order Request

Create Read

Update Delete

Where is the Order ?

400 Bad Request (Request has been rejected)

◦ Client sends malformed order request to the server

◦ Client shouldn’t retry to submit the same order.

CRUD Web services

Malformed Order ResponseMalformed Order Request

Create Read

Update Delete

500 Internal Server Error◦ Indicates a server fault and inability to recover internally

◦ Try Again Later.

◦ Client can try to GET the current representations of another resources (GET is safe)

◦ Server –if in a recoverable state- cleans up any state created by the failed interaction, to keep its own internal order state consistent.

CRUD Web servicesCrea

te Read

Update Delete

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

503 Service Unavailable ◦ Indicates the server is temporarily too busy to process the

request

◦ Has to be associated with Retry-After header.

CRUD Web servicesCrea

te Read

Update Delete

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

GET is used to retrieve a particular representation of a resource.

Usually follows a POST request.

Use Location header in a POST response, to retrieve the current state of a created resource

CRUD Web servicesCreat

e Read

Update Delete

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

200 OK / 204 No-Content (Request has been accepted)


e Read

Update Delete

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

404 NOT Found (Request has been rejected)


e Read

Update Delete

Read Order 404 ResponseRead Order Request

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

500 Internal Server Error◦ Consumer can retry the request after while (GET is idempotent)

◦ Either wait till the service comes back, or accept to hand over control to an out-of-band mechanism.


e Read

Update Delete

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

PUT is used to update a resource.

State of the resource is updated to reflect the data in the request representation


e Read

Update Delete

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

200 OK / 204 No Content (Request has been accepted)

CRUD Web services

OK ResponseUpdate Order Request

Create Read

Update Delete

No Content Response

409 Conflict / 405 Method Not Allowed (Request has been rejected)

Choosing between 409 and 405 depends on the use case

CRUD Web services

409 Response

Create Read

Update Delete

Already Served

500 Internal Server Error (Request has been rejected) Consumer can safely repeat the operation (PUT is idempotent)


e Read

Update Delete

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

CRUD Web services DELETE is used as a request to delete a resource.

It can be used to cancel an order and not physically delete it.

Create Read

UpdateDelete

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

Helps to align Resources State in multi-consumer scenarios.

The server hashes the resource representation in the response.

Consumer are recommended to perform subsequent conditional requests through the (If-Match / If-Not-Match request header)

Saves Server-Side Computations

Out of synch state, and 409 error codes, are less frequent.

ETags

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

ETags

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

HYPERMEDIA WEB SERVICES

Level 3

J u s t A r r i v e d !

Plain XML representation leaves the consumer without a guide to successfully complete the business transaction it has initiated.

Guides may include:◦ Written documentation.◦ Static contracts such as WADL, or URI templates.◦ Hypermedia (expose entry point URI’s and let

Hypermedia take over) ex: http://restbucks.com/order

The Problem

Level 3

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

< o r d e r x m l n s =h t t p : / / s c h e m a s . r e s t b u c k s . c om . o r d e r>< l o c a t i o n > t a k e a w a y < /l o c a t i o n > < n a m e > l a t t e < / n a m e > < q t y > 2 < / q t y > < m i l k > s k i m m e d < / m i l k > < s i z e > s m a l l < / s i z e > < s t a t u s > p e n d i n g < / s t a t u s >< / o r d e r >

Doesn’t indicate the current

state of the business process

or how to advance it!

http://schemas.restbucks.com.order/

http://schemas.restbucks.com.order/

Hypermedia As The Engine Of Application State

By Transiting links between resources, we change the state of an application (world wide

web).

Application state is a snapshot of the entire system at a particular instant.

HATEOAS

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

Order Created

Order Updated

Order Paid

Order Ready

Order Delivere

d

Domain Application

Protocol

HATEOAS

A way for the service to enforce its Domain Application Protocol (DAP).

Convey protocol information in a declarative and just-in-t ime fashion as part of an application’s resource representations.

Sits atop HTTP and narrow HTTP’s broad application protocol capabilities to support specific business goals.

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

Specifies legal interactions between a consumer and a set of resources involved in a business process.

HATEOAS

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

Custom format would require a custom Media Type.

Specify Custom Media Type via the Content-Type HTTP Header.

Media type value indicates the service’s preferred scheme for interpreting a representation.

Media type specification sets out the formats (and any schemas), processing model and hypermedia controls that services will embed in representations.

Consuming Hypermedia

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

Nader

see if it will remain or not

Application Custom Media Type: (application/vnd.restbucks+xml)

The vnd.restbucks sub type marks the payload as being part of Restbucks’ DAP.

The generic application/xml would give wrong indication, and lead to skipping hypermedia benefits.

Consuming Hypermedia

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

Hypermedia Example

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

Hypermedia Example

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

<order xmlns=″http://schemas.restbucks.com″ xmlns:dap=″http://schemas.restbucks.com/dap″>

<dap:link mediaType=″application/vnd.restbucks+xml″ uri=″http://restbucks.com/order/1234″ rel=″http://relations.restbucks.com/cancel″/><dap:link mediaType=″application/vnd.restbucks+xml″ uri=″http://restbucks.com/payment/1234″ rel=″http://relations.restbucks.com/payment″/> <dap:link mediaType=″application/vnd.restbucks+xml″ uri=″http://restbucks.com/order/1234″ rel=″http://relations.restbucks.com/update″/><dap:link mediaType=″application/vnd.restbucks+xml″ uri=″http://restbucks.com/order/1234″ rel=″self″/>

< l o c a t i o n > t a k e a w a y < / l o c a t i o n > < n a m e > l a t t e < / n a m e > < q t y > 2 < / q t y > < m i l k > s k i m m e d < / m i l k > < s i z e > s m a l l < / s i z e > < s t a t u s > u n p a i d < / s t a t u s >

</order>

Unpaid Order

Representation

Hypermedia Example

POX Services

URI Tunneling

CRUD Web Services

Hypermedia

<payment xmlns=″http://schemas.restbucks.com″>< a m o u n t > 2 . 0 < / a m o u n t >< c a r d h o l d e r N a m e > M i c h a e l < / c a r d h o l d e r N a m e >< c a r d N u m b e r > 1 1 2 2 3 3 4 4 < / c a r d N u m b e r >< e x p i r y M o n t h > 1 2 < / e x p i r y M o n t h >< e x p i r y Ye a r > 1 2 < / e x p i r y Ye a r >

</payment>

<ns2:payment xmlns:dap=″http://schemas.restbucks.com/dap″ xmlns=″http://schemas.restbucks.com″><dap:link mediaType=″ application/vnd.restbucks+xml ″ uri=″http://restbucks.com/order/1234″ rel=″http://relations.restbucks.com/order″/><dap:link mediaType=″ application/vnd.restbucks+xml ″ uri=″http://restbucks.com/receipt/1234″ rel=″http://relations.restbucks.com/receipt″/>

< a m o u n t > 2 . 0 < / a m o u n t >< c a r d h o l d e r N a m e > M i c h a e l < / c a r d h o l d e r N a m e >< c a r d N u m b e r > 1 1 2 2 3 3 4 4 < / c a r d N u m b e r >< e x p i r y M o n t h > 1 2 < / e x p i r y M o n t h >< e x p i r y Ye a r > 1 2 < / e x p i r y Ye a r >

</payment>

Payment Response

Payment Route

Chosen

Caching Quick Overview

Reduce Bandwidth

Reduce Latency

Reduce Load

Hide Network Failure

Reduce the statelessness problem

Benefits

Responses to GET requests are cacheable by default.

Responses to POST requests are not cacheable by default, but can be made cacheable.

Responses to PUT and DELETE requests are not cacheable at all.

Caching Responses

Expires◦ Can be used in the Response◦ Specifies an absolute expiry time for a cached representation.◦ Beyond that time, a cached representation is considered stale

and must be revalidated with the origin server.

Cache-Control◦ Can be used in the Request and the Response◦ Comprises one or more directive. ◦ Determines whether a response is cacheable, and if so, by whom,

and for how long.

Caching Response Headers

Caching Example

GET /product-catalog/9876Host: restbucks.comC a c h e - C o n t r o l : n o -c a c h e

D a t e : Fri, 26 Mar 2010 12:07:22 GMTC a c h e - C o n t r o l : max-age=3600L a s t - M o d i fi e d : Fri, 26 Mar 2010 11:45:00 GMTE Ta g : ″59c6dd9f″



< n a m e > C o ff e e B e a n s < / n a m e >< s i z e > 1 k g < / s i z e > 1 2 



D a t e : Fri, 26 Mar 2010 12:07:22 GMTExpires: Sat, 27 Mar 2010 09:33:49 GMTLast-Modified: Fri, 26 Mar 2010 09:33:49 GMTETag: ″cde893c4″ 

< n a m e > C o ff e e B e a n s < / n a m e >< s i z e > 1 k g < / s i z e > 1 2 

Cacheable

response.

Remains fresh for 1

hour

Cacheable

response.

Response is never cached Used by the

Cache Server for

revalidation

Remains fresh until this time

TipsAt a Glance

URI’s should be intuitive and not magical.

Use nouns and not verbs.

Follow the safe / idempotent rule.

Unique identifiers should come as part of the URI.

Tips

Issues and Challenges

ReST may not fit well in every situation

URI Design is quite challenging.

Requires deep understanding of the domain model structure.

Extensive query parameters remains a problem.

Key Issues and Challenges

REST in Practice: Hypermedia and Systems Architecture, Jim Webber, et al., 2010, O’Reilly Media, inc.

http://www.infoq.com/minibooks/emag-03-2010-rest http://www.infoq.com/articles/roa-rest-of-rest http://www.restapitutorial.com/

References

http://www.infoq.com/minibooks/emag-03-2010-rest

http://www.infoq.com/articles/roa-rest-of-rest

http://www.restapitutorial.com/

Questions

THANK YOU

ReST

Technology

Transcript of ReST