REST: The Definition

Outline (REST: The Definition)

REST: The Definition [6]
Web Architecture [6]
1. Uniform Resource Identifier (URI) [2]
2. Hypertext Transfer Protocol (HTTP) [3]
Representations [7]
1. Structured Documents [5]
2. Linked Documents [2]
State [6]

REST: The Definition E. Wilde: Representational State Transfer (REST)

(4) The REST Architectural Style

A set of constraints that inform an architecture

Resource Identification [Resource Identification (1)]
Uniform Interface [Uniform Interface (1)]
Self-Describing Messages [Self-Describing Messages (1)]
Hypermedia Driving Application State [Hypermedia Driving Application State (1)]
Stateless Interactions [Stateless Interactions (1)]

Claims: scalability, mashup-ability, usability, accessibility

REST: The Definition E. Wilde: Representational State Transfer (REST)

(5) Resource Identification

Name everything that you want to talk about
Thing in this case should refer to anything
- products in an online shop
- categories that are used for grouping products
- customers that are expected to buy products
- shopping carts where customers collect products
Application state also is represented as a resource
- next links on multi-page submission processes
- paged results with URIs identifying following pages

REST: The Definition E. Wilde: Representational State Transfer (REST)

(6) 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 nouns
verbs are universal and not invented on a per-application base
if many applications need new verbs, the uniform interface can be extended
natural language works in the same way (new verbs rarely enter language)
Identify operations that are candidates for optimization
- GET and HEAD are safe operations
- PUT and DELETE are idempotent operations
- POST is the catch-all and can have side-effects
Build functionality based on useful properties of these operations

REST: The Definition E. Wilde: Representational State Transfer (REST)

(7) Self-Describing Messages

Resources are abstract entities (they cannot be used per se)
- Resource Identification [Resource Identification (1)] guarantees that they are clearly identified
- they are accessed through a Uniform Interface [Uniform Interface (1)]
Resources are accessed using resource representations
- resource representations are sufficient to represent a resource
- it is communicated which kind of representation is used
- representation formats can be negotiated between peers
Resource representations can be based on different constraints
- XML and JSON can represent the same model for different users
- whatever the representation is, it must support links [Hypermedia Driving Application State (1)]

REST: The Definition E. Wilde: Representational State Transfer (REST)

(8) 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 links
- links make interconnected resources navigable
- without navigation, identifying new resources is service-specific
RESTful applications navigate instead of calling
- representations [Self-Describing Messages (1)] contain information about possible traversals
- the application navigates to the next resource depending on link semantics
- navigation can be delegated since all links use identifiers [Resource Identification (1)]

REST: The Definition E. Wilde: Representational State Transfer (REST)

(9) Stateless Interactions

This constraint does not say Stateless Applications!
- for many RESTful applications, state is an essential part
- the idea of REST is to avoid long-lasting transactions in applications
Statelessness means to move state to clients or resources
- the most important consequence: avoid state in server-side applications
Resource state is managed on the server
- it is the same for every client working with the service
- when a client changes resource state other clients see this change as well
Client state is managed on the client
- it is specific for a client and thus has to be maintained by each client
- it may affect access to server resources, but not the resources themselves
Security issues usually are important with client state
- clients can (try to) cheat by lying about their state
- keeping client state on the server is expensive (but may be worth the price)

Web Architecture

Outline (Web Architecture)

REST: The Definition [6]
Web Architecture [6]
1. Uniform Resource Identifier (URI) [2]
2. Hypertext Transfer Protocol (HTTP) [3]
Representations [7]
1. Structured Documents [5]
2. Linked Documents [2]
State [6]

Web Architecture E. Wilde: Representational State Transfer (REST)

(11) 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 calls
- a 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 state
- what 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-based
- cookies are shared across browser windows (different client scope)

Uniform Resource Identifier (URI)

Outline (Uniform Resource Identifier (URI))

REST: The Definition [6]
Web Architecture [6]
1. Uniform Resource Identifier (URI) [2]
2. Hypertext Transfer Protocol (HTTP) [3]
Representations [7]
1. Structured Documents [5]
2. Linked Documents [2]
State [6]

Uniform Resource Identifier (URI) E. Wilde: Representational State Transfer (REST)

(13) 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 important
- it removes the necessity to scope non-universal identifiers
- it allows to talk about all things in exactly the same way

Uniform Resource Identifier (URI) E. Wilde: Representational State Transfer (REST)

(14) URI Schemes

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

URIs in their general case are very simple
- the scheme identifies how resources are identified
- the identification may be hierarchical or non-hierarchical
Many URI schemes are hierarchical
- it 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 may further restrict the syntax and semantics of identifiers using that scheme.

Uniform Resource Identifier (URI): Generic Syntax, RFC 3986, January 2005 [http://tools.ietf.org/html/rfc3986]

Hypertext Transfer Protocol (HTTP)

Outline (Hypertext Transfer Protocol (HTTP))

REST: The Definition [6]
Web Architecture [6]
1. Uniform Resource Identifier (URI) [2]
2. Hypertext Transfer Protocol (HTTP) [3]
Representations [7]
1. Structured Documents [5]
2. Linked Documents [2]
State [6]

Hypertext Transfer Protocol (HTTP) E. Wilde: Representational State Transfer (REST)

(16) 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 resources
Misusing HTTP turns application into non-RESTful applications
- they lose the capability to be used just by adhering to REST principles
- it's a bad sign when you think you need an interface description language
Extending HTTP turns applications into more specialized RESTful applications
- may be appropriate when more operations are required
- seriously reduces the number of potential clients

Hypertext Transfer Protocol (HTTP) E. Wilde: Representational State Transfer (REST)

(17) HTTP Methods

Safe methods can be ignored or repeated without side-effects
- arithmetically safe: 41 × 1 × 1 × 1 × 1 …
- in practice, without side-effects means without relevant side-effects
Idempotent methods can be repeated without side-effects
- arithmetically 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 care
HTTP has two main safe methods: GET HEAD
HTTP has two main idempotent methods: PUT DELETE
HTTP has one main overload method: POST

Hypertext Transfer Protocol (HTTP) E. Wilde: Representational State Transfer (REST)

(18) Cookies

Cookies are client site state bound to a domain
- they are convenient because they work without having to use a representation
- they are inconvenient because they are not embedded in representations
Cookies are managed by the client
- they are shared across browser tabs
- they are not shared across browsers used by the same user
- essentially, the client model of cookies is a bit outdated
Two major things to look out for when using cookies:
1. session IDs are application state (i.e., non-resource state)
2. cookies break the back button (requests contain a URI/cookie combo)
The ideal RESTful cookie is never sent to the server
- cookies as persistent data storage on the client
- interactions with the server are only using URIs and representations

Representations

Outline (Representations)

REST: The Definition [6]
Web Architecture [6]
1. Uniform Resource Identifier (URI) [2]
2. Hypertext Transfer Protocol (HTTP) [3]
Representations [7]
1. Structured Documents [5]
2. Linked Documents [2]
State [6]

Structured Documents

Outline (Structured Documents)

REST: The Definition [6]
Web Architecture [6]
1. Uniform Resource Identifier (URI) [2]
2. Hypertext Transfer Protocol (HTTP) [3]
Representations [7]
1. Structured Documents [5]
2. Linked Documents [2]
State [6]

Structured Documents E. Wilde: Representational State Transfer (REST)

(21) 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 resource
- resources are never exchanged or otherwise processed directly
- all interactions use resource representations
Representations depend on various factors
- the nature of the resource
- the capabilities of the server
- the capabilities or the communications medium
- the capabilities of the client
- requirements and constraints from the application scenario
- negotiations to figure out the best representation
Representations are identified by media type

Structured Documents E. Wilde: Representational State Transfer (REST)

(22) Extensible Markup Language (XML)

The language that started it all
- created as a streamlined version of SGML
- took 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 vocabularies
XML is only syntax and has almost zero semantics
- very minimal built-in semantics (language identification, IDs, relative URIs)
- semantics are entirely left to the XML vocabularies
XML is built around a tree model
- each XML document is a tree and thus limited in structure
- RESTful XML introduces hypermedia to turn XML data into a graph

Structured Documents E. Wilde: Representational State Transfer (REST)

(23) JavaScript Object Notation (JSON)

The XMLHttpRequest API has been built for requesting XML via HTTP
- this is useful because XML is the most popular data format
- all requested data has to be processed by using XML access methods in JavaScript
JavaScript does not have XML as its internal data model
- the XML received via XMLHttpRequest has to be parsed into a DOM tree
- DOM access in JavaScript is inconvenient for complex operations
- alternatively, the XML can be mapped to JavaScript objects (also requires parsing)
JavaScript Object Notation (JSON) [XML Varia; JavaScript Object Notation (JSON) (1)] encodes data as JavaScript objects
- more efficient for the consumer if the consumer is written in JavaScript
- this turns the generally usable XML service into a JavaScript-oriented service
- for large-scale applications, it might make sense to provide XML and JSON
- this can be negotiated with HTTP content negotiation

Structured Documents E. Wilde: Representational State Transfer (REST)

(24) 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.xml

{ "menu" : {
 "id" : "file",
 "value" : "File",
 "popup" : {
  "menuitem" : [
   { "value" : "New", "onclick" : "CreateNewDoc()" },
   { "value" : "Open", "onclick" : "OpenDoc()" },
   { "value" : "Close", "onclick" : "CloseDoc()" }
  ]
 }
}}

menu.json

Structured Documents E. Wilde: Representational State Transfer (REST)

(25) Atom

A language for representing syndication feeds
Much more modest in its goal than XML [Extensible Markup Language (XML) (1)] or RDF [XML Varia; Semantic Web & Linked Data (1)]
- models feeds as a sets of entries with associated metadata
- uses an XML vocabulary for representing the data model
- uses links for expressing relationships in the data model
Will be discussed in detail as a good foundation for REST [Atom Syndication Format]

Linked Documents

Outline (Linked Documents)

REST: The Definition [6]
Web Architecture [6]
1. Uniform Resource Identifier (URI) [2]
2. Hypertext Transfer Protocol (HTTP) [3]
Representations [7]
1. Structured Documents [5]
2. Linked Documents [2]
State [6]

Linked Documents E. Wilde: Representational State Transfer (REST)

(27) Making Resources Navigable

Essential for using Hypermedia Driving Application State [Hypermedia Driving Application State (1)]
RPC-oriented systems need to expose the available functions
- functions are essential for interacting with a service
- introspection or interface descriptions make functions discoverable
RESTful systems use a Uniform Interface [Uniform Interface (1)]
- no need to learn about functions
- but how to find resources?
1. find them by following links from other resources
2. learn about them by using URI Templates [URI Templates (1)]
3. understand them by recognizing representations

Linked Documents E. Wilde: Representational State Transfer (REST)

(28) URI Templates

REST does not care about URI details
Apart 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 URIs
- URIs should not be guessed based on previously encountered URIs
URI hacking on the Web works and can be useful
- Firefox Go Up [http://dret.typepad.com/dretblog/2008/07/go-up.html] allows easy navigation up one level
- good URIs and bad UIs sometimes turn the address bar into a useful UI
Technically speaking, URI templates are not required by REST
- practically speaking, URI templates are a useful best practice
- all URI navigable resources should also be navigable using representations

State

Outline (State)

REST: The Definition [6]
Web Architecture [6]
1. Uniform Resource Identifier (URI) [2]
2. Hypertext Transfer Protocol (HTTP) [3]
Representations [7]
1. Structured Documents [5]
2. Linked Documents [2]
State [6]