What is REST? - dret.netdret.net/netdret/docs/soa-rest-icwe2009/rest.pdf · representation formats can be negotiated between peers ... What is REST? Hypermedia Driving Application

What is REST?

From SOA to REST:Designing and Implementing RESTfulServices [./]

Tutorial at ICWE 2009[http://icwe2009.webengineering.org/] (SanSebastián, Spain)

Erik Wilde (UC Berkeley School of Information)

June 22, 2009

[http://creativecommons.org/licenses/by/3.0/]

This work is licensed under a CCAttribution 3.0 Unported License [http://creativecommons.org/licenses/by/3.0/]

Contents

2

4

5

6

7

8

9

10

12

13

14

15

16

17

19

21

22

23

24

26

Erik Wilde: What is REST?

ContentsAbstract

1 Abstraction Layers

What is REST?

What is Architecture?

Architecture Examples

Architecture vs. Design

Architectural Styles

REST is not an Architecture

SOA is not an Architecture

2 REST: The Definition

The REST Architectural Style

Resource Identification

Uniform Interface

Self-Describing Messages

Hypermedia Driving Application State

Stateless Interactions

3 Web Architecture

What is the Web?

3.1 Uniform Resource Identifier (URI)

Identifying Resources on the Web

URI Schemes

Query Information

Processing URIs

3.2 Hypertext Transfer Protocol (HTTP)

How RESTful Applications Talk

27

28

31

32

33

34

35

36

38

39

41

42

43

44

45

46

47

HTTP Methods

Cookies

4 Representations

4.1 Structured Documents

What is identified by a URI?

Extensible Markup Language (XML)

JavaScript Object Notation (JSON)

JSON Example

Resource Description Framework (RDF)

Atom

4.2 Linked Documents

Making Resources Navigable

URI Templates

5 State

State Management on the Web

State in HTML or HTTP

State in the Server Application

State as a Resource

Stateless Shopping

Reusing Resources

Conclusions

(2)


AbstractRepresentational State Transfer (REST) is defined as an architectural style, which means that it is not a concretesystems architecture, but instead a set of constraints that are applied when designing a systems architecture. Webriefly discuss these constraints, but then focus on explaining how the Web is one such systems architecture thatimplements REST. In particular, the mechanisms of the Uniform Resource Identifiers (URIs), the Hypertext TransferProtocol (HTTP), media types, and markup languages such as the Hypertext Markup Language (HTML) and theExtensible Markup Language (XML). We also introduce Atom and the Atom Publishing Protocol (AtomPub) as twoestablished ways on how RESTful services are already provided and used on today's Web.

Abstraction Layers

(4)What is REST?

Defining Representational State Transfer: 3 popular definitions

An architectural style for building loosely coupled systemsdefined by a set of very general constraints (principles)the Web (URI/HTTP/HTML/XML) is an instance of this style

1.

The Web used correctly (i.e., not using the Web as transport)HTTP is built according to RESTful principlesservices are built on top of Web standards without misusing themmost importantly, HTTP is an application protocol (not a transport protocol)

2.

Anything that uses HTTP and XML (XML without SOAP)XML-RPC was the first approach for thisviolates REST because there is no uniform interface

3.

Abstraction Layers

(5)


What is Architecture?

What is the “A” in SOA?Architecture is constraint-based design

constraints are derived from requirements (“contextualized requirements”)design without constraints probably is art

Constraints can be derived from a wide variety of sourcestechnical infrastructure (current landscape and expected developments)business considerations (current landscape and expected developments)time horizon (short-term vs. long-term requirements)existing architecturescalabilityperformance (based on performance requirements and definitions)cost (development, deployment, maintenance)

Abstraction Layers

(6)


Architecture Examples

Abstraction Layers

(7)


Architecture vs. Design

Abstraction Layers

(8)


Architectural Styles

Architectural Style vs. ArchitectureArchitectural Style: General principles informing the creation of an architectureArchitecture: Designing a solution to a problem according to given constraintsArchitectural styles inform and guide the creation of architectures

Architecture: Louvre [http://en.wikipedia.org

/wiki/Louvre]

Architectural Style: Baroque[http://en.wikipedia.org/wiki/Baroque_architecture]

Architecture: Villa Savoye [http://en.wikipedia.org

/wiki/Villa_Savoye]

Architectural Style: International Style [http://en.wikipedia.org

/wiki/International_Style_(architecture)]

Abstraction Layers

(9)


REST is not an Architecture

REST is an architectural styledistilled from the Web a posteriorisome of the Web's standards and practices are not perfectly RESTful

The Web is an information system following RESTIt is possible to design other RESTful information systems

different uniform interfaces (not using HTTP's methods)different representations (not using HTML or XML)different identification (not using URIs)

Abstraction Layers

(10)


SOA is not an Architecture

SOA is more a style than an architectureSOA's biggest problem: What is a service?

is a service something that is described by RPC-like custom functions?is a service exposed through a uniform interface?

OASIS [http://www.oasis-open.org/] has a SOA Reference Model TC [http://www.oasis-open.org/committees

/tc_home.php?wg_abbrev=soa-rm]

the Reference Model [http://docs.oasis-open.org/soa-rm/v1.0/soa-rm.pdf] defines a “service” as “a mechanism to enableaccess to one or more capabilities, where the access is provided using a prescribed interface and is exercisedconsistent with constraints and policies as specified by the service description.”the Reference Architecture [http://docs.oasis-open.org/soa-rm/soa-ra/v1.0/soa-ra-pr-01.pdf] describes a WS-* orientedworld view

SOA can be done RESTfully or notwhether a RESTful approach makes sense depends on the constraintsif the constraints allow REST, there should be a good reason for ignoring REST

REST: The Definition

(12)The REST Architectural Style

A set of constraints that inform an architecture

Resource Identification [Resource Identification (1)]1.Uniform Interface [Uniform Interface (1)]2.Self-Describing Messages [Self-Describing Messages (1)]3.Hypermedia Driving Application State [Hypermedia Driving Application State (1)]4.Stateless Interactions [Stateless Interactions (1)]5.

Claims: scalability, mashup-ability, usability, accessibility


(13)


Resource Identification

Name everything that you want to talk about“Thing” in this case should refer to anything

products in an online shopcategories that are used for grouping productscustomers that are expected to buy productsshopping carts where customers collect products

Application state also is represented as a resourcenext links on multi-page submission processespaged results with URIs identifying following pages


(14)


Uniform Interface

The same small set of operations applies to everything [Resource Identification (1)]

A small set of verbs applied to a large set of nounsverbs are universal and not invented on a per-application baseif many applications need new verbs, the uniform interface can be extendednatural language works in the same way (new verbs rarely enter language)Identify operations that are candidates for optimization

GET and HEAD are safe operationsPUT and DELETE are idempotent operationsPOST is the catch-all and can have side-effects

Build functionality based on useful properties of these operations


(15)


Self-Describing Messages

Resources are abstract entities (they cannot be used per se)Resource Identification [Resource Identification (1)] guarantees that they are clearly identifiedthey are accessed through a Uniform Interface [Uniform Interface (1)]

Resources are accessed using resource representationsresource representations are sufficient to represent a resourceit is communicated which kind of representation is usedrepresentation formats can be negotiated between peers

Resource representations can be based on different constraintsXML and JSON can represent the same model for different userswhatever the representation is, it must support links [Hypermedia Driving Application State (1)]


(16)


Hypermedia Driving Application State

Resource representations [Self-Describing Messages (1)] contain links to identified resources [Resource Identification (1)]

Resources and state can be used by navigating linkslinks make interconnected resources navigablewithout navigation, identifying new resources is service-specific

RESTful applications navigate instead of callingrepresentations [Self-Describing Messages (1)] contain information about possible traversalsthe application navigates to the next resource depending on link semanticsnavigation can be delegated since all links use identifiers [Resource Identification (1)]


(17)


Stateless Interactions

This constraint does not say “Stateless Applications”!for many RESTful applications, state is an essential partthe idea of REST is to avoid long-lasting transactions in applications

Statelessness means to move state to clients or resourcesthe most important consequence: avoid state in server-side applications

Resource state is managed on the serverit is the same for every client working with the servicewhen a client changes resource state other clients see this change as well

Client state is managed on the clientit is specific for a client and thus has to be maintained by each clientit may affect access to server resources, but not the resources themselves

Security issues usually are important with client stateclients can (try to) cheat by lying about their statekeeping client state on the server is expensive (but may be worth the price)

Web Architecture

(19)What is the Web?

Web = URI + HTTP + ( HTML | XML )RESTful Web uses HTTP methods as the uniform interface

non-RESTful Web uses GET/POST and tunneled RPC callsa “different RESTful Web” uses Web Distributed Authoring and Versioning (WebDAV)

Imagine your application being used in “10 browsers”resources to interact with should be identified [Resource Identification (1)] and linked [Hypermedia Driving Application State

(1)]

a user's preferred font size could be modeled as client statewhat about an access count associated with an API key?

Imagine your application being used in “10 browser tabs”no difference as long as client state is representation-basedcookies are shared across browser windows (different “client scope”)

Uniform Resource Identifier (URI)

(21)Identifying Resources on the Web

Essential for implementing a Resource Identification [Resource Identification (1)]

URIs are human-readable universal identifiers for “stuff”many identification schemes are not human-readable (binary or hex strings)many RPC-based systems do not have universally identified objects

Making every thing a universally unique identified thing is importantit removes the necessity to scope non-universal identifiersit allows to talk about all things in exactly the same way


(22)


URI SchemesURI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

URIs in their general case are very simplethe scheme identifies how resources are identifiedthe identification may be hierarchical or non-hierarchical

Many URI schemes are hierarchicalit is then possible to use relative URIs such as in a href="../"the slash character is not just a character, in URIs it has semantics

[…] the URI syntax is a federated and extensible naming system wherein each scheme's specification mayfurther restrict the syntax and semantics of identifiers using that scheme.

“Uniform Resource Identifier (URI): Generic Syntax”, RFC 3986, January 2005 [http://dret.net/rfc-index/reference/RFC3986]


(23)


Query Information

Query components specify additional informationit is non-hierarchical information further identifying the resourcein most cases, it can be regarded as “input” to the resource

Query components often influence cachingsuccessful GET/HEAD requests may be cachedonly cache query string URIs when explicitly requested (Expires/Cache-Control)

The query component contains non-hierarchical data that, along with data in the path component […], servesto identify a resource within the scope of the URI's scheme and naming authority […].

“Uniform Resource Identifier (URI): Generic Syntax”, RFC 3986, January 2005 [http://dret.net/rfc-index/reference/RFC3986]


(24)


Processing URIs

Processing URIs is not as trivial as it may seemescaping and normalization rules are non-trivialmany implementations are brokencomplain about broken implementationseven more complicated when processing an Internationalized Resource Identifier (IRI)

URIs are not just stringsURIs are strings with a considerable set of rules attached to themimplementing all these rules is non-trivialimplementing all these rules is crucialapplication development environments provide functions for URI handling

Hypertext Transfer Protocol (HTTP)

(26)How RESTful Applications Talk

Essential for implementing a Uniform Interface [Uniform Interface (1)]

HTTP defines a small set of methods for acting on URI-identified resourcesMisusing HTTP turns application into non-RESTful applications

they lose the capability to be used just by adhering to REST principlesit's a bad sign when you think you need an interface description language

Extending HTTP turns applications into more specialized RESTful applicationsmay be appropriate when more operations are requiredseriously reduces the number of potential clients


(27)


HTTP Methods

Safe methods can be ignored or repeated without side-effectsarithmetically safe: 41 × 1 × 1 × 1 × 1 …in practice, “without side-effects” means “without relevant side-effects”

Idempotent methods can be repeated without side-effectsarithmetically idempotent: 41 × 0 × 0 × 0 × 0 …in practice, “without side-effects” means “without relevant side-effects”

Unsafe and non-idempotent methods should be treated with careHTTP has two main safe methods: GET HEADHTTP has two main idempotent methods: PUT DELETEHTTP has one main overload method: POST


(28)


Cookies

Cookies are client site state bound to a domainthey are convenient because they work without having to use a representationthey are inconvenient because they are not embedded in representations

Cookies are managed by the clientthey are shared across browser tabsthey are not shared across browsers used by the same useressentially, the client model of cookies is a bit outdated

Two major things to look out for when using cookies:session IDs are application state (i.e., non-resource state)1.cookies break the back button (requests contain a “URI/cookie” combo)2.

The ideal RESTful cookie is never sent to the servercookies as persistent data storage on the clientinteractions with the server are only using URIs and representations

Representations

Structured Documents

(31)What is identified by a URI?

Essential for implementing Self-Describing Messages [Self-Describing Messages (1)]

also should provide support for Hypermedia Driving Application State [Hypermedia Driving Application State (1)]

Resource Identification [Resource Identification (1)] only talks about an abstract resourceresources are never exchanged or otherwise processed directlyall interactions use resource representations

Representations depend on various factorsthe nature of the resourcethe capabilities of the serverthe capabilities or the communications mediumthe capabilities of the clientrequirements and constraints from the application scenarionegotiations to figure out the “best” representation

Representations are identified by media type (sometimes called MIME type) [http://dret.net/lectures/web-fall08/mediatypes]


(32)


Extensible Markup Language (XML)

The language that started it allcreated as a streamlined version of SGMLtook over as the first universal language for structured data

XML is a metalanguage (a language for representing languages)many domain-specific languages are defined as XML vocabulariessome metalanguages use XML syntax (RDF [Resource Description Framework (RDF) (1)] is a popular example)

XML is only syntax and has almost zero semanticsvery minimal built-in semantics (language identification, IDs, relative URIs)semantics are entirely left to the XML vocabularies

XML is built around a tree modeleach XML document is a tree and thus limited in structureRESTful XML introduces hypermedia to turn XML data into a graph


(33)


JavaScript Object Notation (JSON)

The XMLHttpRequest API has been built for requesting XML via HTTPthis is useful because XML is the most popular data formatall requested data has to be processed by using XML access methods in JavaScript

JavaScript does not have XML as its internal data modelthe XML received via XMLHttpRequest has to be parsed into a DOM treeDOM access in JavaScript is inconvenient for complex operationsalternatively, the XML can be mapped to JavaScript objects (also requires parsing)

JavaScript Object Notation (JSON) encodes data as JavaScript objectsmore efficient for the consumer if the consumer is written in JavaScriptthis turns the generally usable XML service into a JavaScript-oriented servicefor large-scale applications, it might make sense to provide XML and JSONthis can be negotiated with HTTP content negotiation


(34)


JSON Example<?xml version="1.0"?>

<menu id="file" value="File">

<popup>

<menuitem value="New" onclick="CreateNewDoc()"/>

<menuitem value="Open" onclick="OpenDoc()"/>

<menuitem value="Close" onclick="CloseDoc()"/>

</popup>

</menu>

{ "menu" : {

"id" : "file",

"value" : "File",

"popup" : {

"menuitem" : [

{ "value" : "New", "onclick" : "CreateNewDoc()" },

{ "value" : "Open", "onclick" : "OpenDoc()" },

{ "value" : "Close", "onclick" : "CloseDoc()" }

]

}

}}


(35)


Resource Description Framework (RDF)

Developed around the same time as XML was developedbased on the idea of machine-readable/understandable semanticsbuilds the Semantic Web as a parallel universe on top of the Web

RDF uses URIs for naming thingsRDF's data model is based on (URI, property, value) triplestriples are combined and inference is used to produce a graph

RDF is a metalanguage built on the triple-based data modelRDF has a number of syntaxes (one of them is XML [Extensible Markup Language (XML) (1)]-based)RDF introduces a number of schema languages (often referred to as ontology languages)


(36)


Atom

A language for representing syndication feedsMuch more modest in its goal than XML [Extensible Markup Language (XML) (1)] or RDF [Resource Description Framework (RDF) (1)]

models feeds as a sets of entries with associated metadatauses an XML vocabulary for representing the data modeluses links for expressing relationships in the data model

Will be discussed in detail as a good foundation for REST [REST in Practice]

Linked Documents

(38)Making Resources Navigable

Essential for using Hypermedia Driving Application State [Hypermedia Driving Application State (1)]

RPC-oriented systems need to expose the available functionsfunctions are essential for interacting with a serviceintrospection or interface descriptions make functions discoverable

RESTful systems use a Uniform Interface [Uniform Interface (1)]

no need to learn about functionsbut how to find resources?find them by following links from other resources1.learn about them by using URI Templates [URI Templates (1)]2.understand them by recognizing representations3.

Linked Documents

(39)


URI Templates

REST does not care about URI detailsApart from the scheme, URIs should be semantically opaque

media types should not guessed by URI (breaks content negotiation)semantics should not be inferred from inspecting URIsURIs should not be guessed based on previously encountered URIs

“URI hacking” on the Web works and can be usefulFirefox Go Up [http://dret.typepad.com/dretblog/2008/07/go-up.html] allows easy navigation up one levelgood URIs and bad UIs sometimes turn the address bar into a useful UI

Technically speaking, URI templates are not required by RESTpractically speaking, URI templates are a useful best practiceall URI navigable resources should also be navigable using representations

State

(41)State Management on the Web

Essential for supporting Stateless Interactions [Stateless Interactions (1)]

Cookies [Cookies (1)] are a frequently used mechanism for managing statein many cases used for maintaining session state (login/logout)more convenient than having to embed the state in every representationsome Web frameworks switch automatically between cookies and URI rewriting

Cookies have two interesting client-side side-effectsthey are stored persistently independent from any representationthey are “shared state” within the context of one browser

Session ID cookies require expensive server-side trackingnot associated with any resource and thus potentially globalload-balancing must be cookie-sensitive or cookies must be global

Resource-based state allows RESTful service extensions

State

(42)


State in HTML or HTTP

State

(43)


State in the Server Application

State

(44)


State as a Resource

State

(45)


Stateless Shopping

Typical “session scenarios” can be mapped to resources [http://www.peej.co.uk/articles/no-sessions.html]

Client: Show me your productsServer: Here's a list of all the productsClient: I'd like to buy 1 of http://ex.org/product/X, I am "John"/"Password"Server: I've added 1 of http://ex.org/product/X to http://ex.org/users/john/basketClient: I'd like to buy 1 of http://ex.org/product/Y, I am "John"/"Password"Server: I've added 1 of http://ex.org/product/Y to http://ex.org/users/john/basketClient: I don't want http://ex.org/product/X, remove it, I am "John"/"Password"Server: I've removed http://ex.org/product/X to http://ex.org/users/john/basketClient: Okay I'm done, username/password is "John"/"Password"Server: Here is the total cost of the items in http://ex.org/users/john/basket

This is more than just renaming “session” to “resource”all relevant data is stored persistently on the serverthe shopping cart's URI can be used by other services for working with its contentsinstead of hiding the cart in the session, it is exposed as a resource

State

(46)


Reusing Resources

(47)


Conclusions

REST is simple to learn and useUnlearning RPC in most cases is the hardest part

OO is all about identifying classes and methodsdistributed systems very often are built around RPC modelsmany classical IT architectures are RPC-centric by design

REST and RPC do not mixresource orientation � function orientationcooperation � integrationopenly distributed � hiding distributioncoarse-grained � fine-grainedcomplexity in resources formats � complexity in function set