Separating REST Facts from Fallacies

Alan Dean

The Web

FallacyREST is just The Web

FactsMuch / most of the Web is not RESTfulREST was described, a posteriori, by Roy Fielding

in his doctoral thesis as the architectural principles underlying HTTP (edited by Fielding et al)○ http://www.ics.uci.edu/~fielding/pubs/dissertation/

REST is The Web done right

Authoritative

FallacyREST is a matter of opinion

FactREST is what Roy says it is

REST is an Architectural Style An architectural style is a coordinated

set of architectural constraints that restricts the roles and features of architectural elements, and the allowed relationships among 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.

Deriving REST

Style = nil Style += Client/Server Style += Stateless Style += Caching Style += Uniform Interface Style += Layered System Style += Code on Demand

Style = nil

Starting from a condition of no constraints…

Style += Client/Server

Apply separation of concerns

improves UI portability simplifies server

enables multiple organizational domains

REST & HTTP

FallacyREST == HTTP

Fact“Good grief. Why does everyone equate REST

with HTTP? REST apps work quite well with file, ftp, gopher, wais, urn, ... I won't even mention waka in that list because it isn't done yet.”○ (Roy Fielding)

HTTP is simply the best known Transfer protocol

Style += Stateless

Constrain interaction to be stateless

simplifies server

improves scalability

improves reliabilitydegrades efficiency

Stateless It is important to differentiate (client)

application state from (server) resource state

FallacyYou can do an end-around of the stateless

constraint by turning application state into resource state

FactThe server should have no knowledge about

application stateThe client is free to use a different server to

persist application state

Style += Caching

Add optional non-shared caching

reduces average latency

improves efficiency

improves scalabilitydegrades reliability

$

$

Style += Uniform Interface Apply generality

$

$

$

degrades efficiency

improves visibility

independent evolvability

decouples implementation

Uniform Interface

Uniform identification of resources Uniform access methods

Universal semantics

Manipulation of resources through the exchange of representations

Self-descriptive messages Hypermedia / hypertext as the engine of

application state

Uniform identification of resources All important resources are identified by

one (uniform) resource identifier mechanism, e.g. a URI

FallacyThe layout of the URI is important to REST

FactsThe layout of the URI is opaque to RESTA ‘human-friendly’ URI is good, regardless

Uniform access methods Actions mean the same for all resources Fallacies

Methods IN { PUT, GET, POST, DELETE }Therefore, REST == CRUD

FactsAny universally understood representation

action can be used, e.g.:○ WebDAV LINK or PATCH but not PROP○ COM IDispatch and IUnknown can be regarded as

uniform COM object ‘GET’ access methodsSome HTTP methods are insufficiently defined

○ Yes, I’m talking “POST” aka “MISCELLANEOUS”

Hypermedia / hypertext as the engine of application state Often abbreviated to HATEOAS Think about media-types Fallacies

Hypertext == HTMLAtom everywhere

FactsExplicit or implicit links support HATEOASLinks exist in non-HTML media-typesThere are more media types than just HTML

and Atom

Roy Fielding on HATEOS“A truly RESTful API looks like hypertext.

Every addressable unit of information carries an address, either explicitly (e.g., link and id attributes)

or implicitly (e.g., derived from the media type definition and representation structure).

Query results are represented by a list of links with summary information, not by arrays of object representations (query is not a substitute for

identification of resources).Resource representations are self-descriptive: the client

does not need to know if a resource [belongs to a specific website] because it is just acting on the

representations received.”

Style += Layered System Apply information hiding

shared caching

improves scalability

$$

$

$

$

$

$

$$

adds latency

simplifies client

legacy encapsulation

load balancing

Style += Code on Demand Allow code-on-demand (applets/js)

simplifies clientsreduces visibility improves extensibility

$$

$

$

$

$

$

$$.js

Simplicity

FallacyREST is simple

FactsREST has simple constraintsRESTful systems are often complex in their

collaborationsTruly RESTful system design is non-trivial

Difficulty

FallacyREST is easy

FactAll distributed system development is hard

○ http://wikipedia.org/wiki/Fallacies_of_Distributed_Computing

REST is not a panacea

Plain Old XML (POX)

FallacyREST is just POX-over-HTTP

FactsPOX (as generally understood) is typically an

RPC stylePOX typically tunnels through HTTP using

POST○ With endpoints that look & act like methods○ Without meeting the constraints of REST○ Content-Type: application/xml is a tell

hi-REST / lo-REST Fallacy

The hi-REST / lo-REST meme○ Started by Don Box

Fact“REST, as styles go, is more like the architecture of

barnyards and office suites. The notion that there is anything lo or hi about it demonstrates a fundamental lack of understanding”○ (Roy Fielding)

You are either RESTful, or not○ You become RESTful by not breaching any constraint

SOAP Services (WS-*) Fallacies

Commit to REST or WS-*REST is the ‘ultimate architecture’

FactsWS-* is not an architectural style

○ SOA == REST nil styleREST is not a protocol stackREST is appropriate when a Resource Oriented

Architecture (ROA) is desirableA system can compose both REST and WS-*We are in a world where some architects still

think you need to commit to one or the other

Standardization Fallacy

Unlike WS-*, REST has no standards Facts

Hymermedia / hypertext is standardized○ fewer UIs

Identification is standardized○ less communication

Exchange protocols are standardized○ fewer integrations

Interactions are standardized○ fewer semantics

Media-types are standardized○ fewer translations

Man –vs- Machine

FallacyRESTful systems are only good for systems

which require human interaction, like web pages

FactA well-written RESTful application protocol

will sufficiently remove ambiguity to allow machine-to-machine interaction○ AtomPub achieves this○ RSS is the counter-example

Interface Definitions

FallacyREST needs a WSDL such as WADL

FactThe whole point of the Uniform Interface

constraint is to remove the need for specialised interface definitions

Authentication Fallacy

It’s OK to use server cookies to authenticate users in REST

Fact“Authentication is orthogonal. Cookies are also

orthogonal when they are simply used for content negotiation or authentication. However, Cookie authentication is not allowed in REST because it lacks visibility, which causes security problems […]”○ (Roy Fielding)

For HTTP, use WWW-Authenticate

Scalability

FallacyRESTful services always scale well

FactNot unless you have implemented cachingNot if interaction requires access control

Transactions

FallacyYou can’t do transactions in REST

FactsYou can do atomic server transactions

within the bounds of a single HTTP requestYou can do compensatory ‘long-running’

and distributed transactions across multiple HTTP requests provided that you don’t break the Layered System constraint

Tools Fallacy

REST needs more tooling before adoption Fact

The tooling to implement REST on HTTP already exists○ However, developers need to throw off their

current mindset and understand RESTThe on-ramp to REST can be made easier with

better tools○ ASP.NET MVC is superior to ASP.NET WebForms

Adoption Facts

Many systems could benefit by adopting a RESTful architecture

Acceptance and adoption has been slow○ This is now changing○ Beware of the gloryhounds who follow

buzzwords but don’t actually grok RESTDo you ETag?

REST is not easy to learn, especially when a previous mindset needs to be set aside

Too many sites wrongly claim a RESTful API

</presentation>Email

[email protected]

Linkshttp://delicious.com/alan.dean/rest

http://alandean.blogspot.comhttp://twitter.com/adean

Acknowledgements“A little REST and Relaxation”

Roy Fielding, 2007 ApacheCon