(20) 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

(21) 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://dret.net/rfc-index/reference/RFC3986]

(22) Query Information

• Query components specify additional information
  • it is non-hierarchical information further identifying the resource
  • in most cases, it can be regarded as input to the resource
• Query components often influence caching
  • successful GET/HEAD requests may be cached
  • only 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 […], serves to 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]

(23) Processing URIs

• Processing URIs is not as trivial as it may seem
  • escaping and normalization rules are non-trivial
  • many implementations are broken
  • complain about broken implementations
  • even more complicated when processing an Internationalized Resource Identifier (IRI)
• URIs are not just strings
  • URIs are strings with a considerable set of rules attached to them
  • implementing all these rules is non-trivial
  • implementing all these rules is crucial
  • application development environments provide functions for URI handling

(25) 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

(26) 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 safe: 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

(27) 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 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

(30) What is 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

(31) 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
  • some metalanguages use XML syntax (RDF [Resource Description Framework (RDF) (1)] is a popular example)
• 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

(32) 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) encodes data as JavaScript objects
  • because the consumer is written in JavaScript, this is more efficient for the consumer
  • this turn 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

(33) 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()" }
  ]
 }
}}

(34) Resource Description Framework (RDF)

• Developed around the same time as XML was developed
  • based on the idea of machine-readable/understandable semantics
  • builds the Semantic Web as a parallel universe on top of the Web
• RDF uses URIs for naming things
  • RDF's data model is based on (URI, property, value) triples
  • triples are combined and inference is used to produce a graph
• RDF is a metalanguage built on the triple-based data model
  • RDF 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)

(35) Atom

• A language for representing syndication feeds
• Much 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 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 [REST in Practice]

(37) 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

(38) 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