An Introduction to

RESTful Services
 The Web as Database


REST, at its core, is very simple:
−    You can treat the web (or at least your part of 
the web) like a database, adding, modifying, 
deleting and retrieving documents as if they 
were records in a data table.
−    RESTful Services extends that concept by 
rethinking the notion of documents in a 
dynamic environment
 RESTful Services: 10,000 ft.


Replace process­oriented services with 
resource­oriented ones

Treat server as addressable database with 
HTTP methods as CRUD operations

Associate multiple presentation & input faces 
with each HTTP operations

Bind each face with a pipeline operation.
 RESTful Services Maturing


Roy Fieldings REST dissertation in 1999

SOAP/WSDL services rise and fall (2000­2008)

Blogging pushes syndication, social networks 
and streaming data (2003­)

AJAX (2004­) and Ruby (2005­)

Rise of Xquery and conformant XML databases 
(2007­)
03/06/09 An Introduction to RESTful Services 4
 Why RESTful Services?


RESTful Services are becoming important:
− Rise of Rich Data (XBRL, NIEM IEPDs, 
Data.gov, S1000D, GML, etc.)
− Cloud computing favors RESTful architectures
− WS APIs cloud analog to vendor lock­in
− Client­side componentization favors RESTful 
services.
− Data models are trumping process models
03/06/09 An Introduction to RESTful Services 5
 Advantages of RESTful Services


RESTful services reduce siloization by 
eliminating process coupling

RESTful services work well with pipeline 
architectures (Xproc) and queries (XQuery) 

RESTful services can also integrate cleanly with 
traditional SOA through those pipelines

RESTful services reduces API complexity

03/06/09 An Introduction to RESTful Services 6

 RESTful Services Issues


Methodologies only now emerging

No formal discovery mechanism for RESTful 
Services.

Works best with URL Rewrite capability

RESTful clients such as Xforms are, while 
maturing, not yet mature

Few product offerings (as yet)
03/06/09 An Introduction to RESTful Services 7
 RESTful Service Implementations


Xquery­XProc/REST/XForms (XRX)

Drupal (PHP)

Atom Publishing Protocol (AtomPub)

Ruby on Rails (limited)

Others

03/06/09 An Introduction to RESTful Services 8

 The Role of Resources

There are no “things” ­ no physical objects ­ on 
the Internet.
•
There are, however, abstractions of things. 
These abstractions are known as resources.
Resources are fundamental to REST and 
RESTful services.

03/06/09 An Introduction to RESTful Services 9

 Resources


Have an explicit or implicit model (schema)

Are made of property values and containers in 
that model (instance)

Have an address (addressable)

Are unique (non­fungible)

Have one or more presentation or input faces 
(representational)
03/06/09 An Introduction to RESTful Services 10
 Representations


A resource is an abstraction. A representation 
provides a “face” for the abstraction.

Some faces are visual: HTML tables, lists, 
records, pages, edit forms, pdfs, etc.

Some faces are more abstract: raw xml, json, csv

All resources can have one or more 
representations

03/06/09 An Introduction to RESTful Services 11

 A Presentation of Representations

Print
Rendered Video Formatted
Audio
Graphics (PDF)

<employee>
<firstname>
Jane Doe is an Jane
employee who </firstname>
works at ACME <lastname>
Widget Works as
a Senior Design Jane Doe, Doe

Bitmap
</lastname>
Engineer. He’s <title>
been here Engineer Engineer
Images nce 1995 .... </title>

(resource)
XML
Text Description
 Static vs. Dynamic


In the “early” web, resources were static: They 
did not change significantly over time (Web pages)

Contemporary resources are dynamic: They are 
time dependent, or streaming. (Twitter)

Thus, at any given time, a representation is a 
“snapshot” of that resource at that time it was 
requested – it's the state of the resource.

03/06/09 An Introduction to RESTful Services 13

 REST 
is Transferring Resource State

Because a resource has an address, it can be 
addressed – content can be sent to it or 
retrieved from it.

You interact with the resource through its 
address.

REST => Representational State Transfer

REST is the transfer of representations of state 
to or from a resource's address
03/06/09 An Introduction to RESTful Services 14
 RESTful Services


A RESTful Service is a web service which 
− Is resource rather than process oriented
− Creates, reads, updates and/or deletes 
resources, collections or views
− Uses a single (base) URL for all of these 
operations on any given resource
− Provides one or more faces (representations) 
for these operations

03/06/09 An Introduction to RESTful Services 15

 Collections


A collection is a set of resources

Collections are also resources:
− They can be represented by a URL
− They can have one or more representations

RSS feeds, index pages, HTML tables & lists, 
etc.

While a directory is a collection, collections can 
be created from arbitrary criteria
03/06/09 An Introduction to RESTful Services 16
 Collections & HTTP


The primary HTTP 1.1 “methods” are all 
collection operations:
− POST adds a new resource to a collection
− GET retrieves a resource from a collection
− PUT replaces a resource within a collection
− DELETE removes a resource from a collection

03/06/09 An Introduction to RESTful Services 17

 HTTP & CRUD


HTTP Operations ~ Database Table Operations
Database CRUD HTTP Methods
Create POST
Read GET
Update PUT
Delete Delete

03/06/09 An Introduction to RESTful Services 18

 HTTP & Databases


A collection is analogous to a database table
− Each resource is analogous to a record or row
− REST operations are set operations
− While not required, most resources in a 
collection share a common data model
− Note that both relational tables and REST 
collections do not maintain session state*
* In theory. In practice, most RESTful systems maintain caches.

03/06/09 An Introduction to RESTful Services 19

 Collections, Queries and Views


A collection can be an existing set of resources

A collection can also be the result of a query 
that filters the result by multiple criteria

Such collections are views, analogous to 
database SQL Views. 

Views are also resources, and can have URLs

03/06/09 An Introduction to RESTful Services 20

Uses of Views


Changing Sort Order

Changing Keys

Establishing Subset

Virtual resources

Post­processing
 Formal vs. Virtual Resources


A formal resource is one where it's internal 
representation matches its external 
representation.

A virtual resource is one where the external 
representation differs from the internal, 
requiring processing.

Formal resources can be managed via virtual 
resource processors (important!)
03/06/09 An Introduction to RESTful Services 22
 RESTful Services vs. Web Services

Comparison of services
Web Services
Process or API Oriented (Imperative)
State is managed by session
Application Data Model is implicit
Mediated by SOAP
Works poorly on the web
Presentation limited part of services
Heavy-weight, works well in heavy
enterprise services
03/06/09 An Introduction to RESTful Services
RESTful Services
Resource Oriented (Declarative)
State is contained within resource
Application Data model is explicit
Mediated by Appropriate Face
Works well on the web
Presentation intrinsic to services
Light-weight, good 90% solution
23
 Typical RESTful Services URLs

http://server/view.face
− Retrieves a representation of the view associated with the face
− /employees/engineering.table.html

/view//key.face
− Retrieves a document instance from the  view, determined by the 
(unique) key, and rendered as the given face
− /employees/engineering//jane_doe.record.html

/view.face?query=queryStr
− Passes the queryStr to the query associated with the view to be parsed 
and expanded into a formal search.
− /employees/engineering.atom.xml?query=specialty:electrical

03/06/09 An Introduction to RESTful Services 24

 A RESTful Architecture

03/06/09 An Introduction to RESTful Services 25

 RESTful Processing


Typically each HTTP method and face is 
associated with a pipeline

Output pipelines perform queries, sorts views, 
paginates and generate faces

Input pipelines perform validation, rectifies 
faces, updates content

Error handling updates Fault Collection

03/06/09 An Introduction to RESTful Services 26

 Collections & Pipelines

Pipelines Reference & Write To Views
If Error
<foo/> Occurs <foo/>
<foo/>
<foo/>
<foo/>
<foo/>
<foo/> parse <foo/>
<foo/>
<err/>

/foo view filter /error view

<foo/> validate
<foo/>
<foo/>
<foo/>
<qry/>
render

/foo/query view

03/06/09 An Introduction to RESTful Services 27

 RESTful Services & Syndication


Syndication (news feeds) are classical RESTful 
applications. Feeds are faces of views or collections.

User subscribes to view showing newest 
content for that view

Links in syndication feeds can then open up 
individual resources in the appropriate face

Model also works well with social network 
apps – Twitter, Facebook, etc.
03/06/09 An Introduction to RESTful Services 28
 RESTful Services & Queries


Depending on implementation, queries can be 
simple, complex or both

Complex queries are uploaded as resources that 
can in turn define new views

Simple queries are passed as a query string 
parameter, then expanded in pipeline

Simple queries are synonymous with “Search”

03/06/09 An Introduction to RESTful Services 29

 Keys


A key is a hashed string that, when resolved, 
will uniquely identify a given document in the 
context of the collection.

Keys can also resolve to sub­documents, such 
that the key identifies both the document and 
the subdocument.

Each collection or view will have a different key 
mechanism.
03/06/09 An Introduction to RESTful Services 30
 Keys & Subdocuments


For instance, in the resource URL:
/docs/airframes//787.doc.html
the key “787” defines which airframe document is referenced for the 
collection airframes

However, in /doc/airframe/left­wing­assembly//787­engassbly.doc.html
the key “787­engassbly” will be parsed to retrieve both the airframe model 
“787” and the subsection “engassbly” (engine assembly).

Subdocuments make it possible to view, edit and validate relevant sub­
portions of a large document without having to send the entire document to 
the client.

Subdocuments may also contain additional “processing” metadata before 
being sent to the client that will be removed upon submission.

03/06/09 An Introduction to RESTful Services 31

 Templates


Any RESTful service that exposes a POST 
method should include a template document 
for each POST (input) face

A template is a “baseline” document that is 
used to create new documents of the given 
schema.

Such a template should use a string like “new”, 
“default” or the like for its primary key.
03/06/09 An Introduction to RESTful Services 32
 RESTful Clients


RESTful clients work with resource instances 
rendered in the appropriate face

Interactive RESTful clients maintain integrity of 
the state instance when sending to server

Faces may be embedded in one another (such 
as through XInclude or AJAX)

Examples: XForms, AJAX components

03/06/09 An Introduction to RESTful Services 33

 Questions?

03/06/09 An Introduction to RESTful Services 34

 Kurt Cagle


Managing Editor, XMLToday.org

Contributing Editor, O'Reilly Media

Chief Architect, Metaphorical Web, Inc.

Available for Consulting and Hire 
(kurt.cagle@gmail.com)

03/06/09 An Introduction to RESTful Services 35