Back to basics
 Plain HTTP
 GET, PUT, DELETE
 XML, JSON or XHTML data

Time for some examples
• iTunes top 10 songs
– http://ax.itunes.apple.com/WebObjects/MZStoreServices.woa/ws/RSS/topsongs/limit=10/xml
• Twitter
– http://twitter.com/statuses/user_timeline/7355792.atom
– http://twitter.com/statuses/user_timeline/7355792.json
– http://twitter.com/friends/ids.json?user_id=7355792
• Google Maps
– http://maps.google.com/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400

How RESTful is it?
 Are all plain HTTP APIs REST?
 Most services that claim to be REST are
actually not
 There are some rules to follow

“Design depends largely on constraints.”
— Charles Eames

Roy Fielding
file:///Users/andreas/Documents/workspace/RestfulSlideshowApplication/war/images/roy_fielding.jpg

Principles of REST
• Give every “thing” an ID
• Use a standard set of methods
• Link things together
• Communicate statelessly

Addressability
 Resources must be addressable
 Everything that matters should have its own
URI

Uniform Interface
 Well defined set of operations
 GET, PUT, DELETE, POST
 Well defined semantics
 GET does not kill kittens
 PUT and DELETE are idempotent
 POST is unsafe
 A client knows exactly what it can do with a
resource

Imagine the web without links

Without linking
GET http://bjarlestam.com/slides
[slide1, slide2, slide3, slide4]
Client Server
GET http://bjarlestam.com/slides/getSlide?id=slide1

With linking
GET http://bjarlestam.com/slides
[ http://bjarlestam.com/slides/slide1,
http://bjarlestam.com/slides/slide2,
http://bjarlestam.com/slides/slide3,
Client http://bjarlestam.com/slides/slide4 ] Server
GET http://bjarlestam.com/slides/slide1

Why is it better to link the resources?

Link your resources
• No out of band info needed
• No separate discovery mechanism

Statelessness

Imagine Google being stateful

Stateful
http://www.google.com/search?q=rest&page=first
http://www.google.com/search?q=rest&page=next
http://www.google.com/search?q=rest&page=next

Stateless
http://www.google.com/search?q=rest
http://www.google.com/search?q=rest&start=10
http://www.google.com/search?q=rest&start=20

What makes the stateless Google
better than the stateful?

Statelessness
• Better scaling
– No session storage on server
– Any server in a cluster can handle any request
– All the result pages can safely be cached
• More reliable
– A client can safely re-send a request
• Better resource reuse
– All the result pages can safely be linked to

Caching

Client
Cache
Client
Client
Cache
Client Proxy
Cache
Client
Cache Server
Client Reverse
Proxy
Cache
Client Proxy
Cache Cache
Client

“The best requests are those that
not even reach me.”
- Anonymous overloaded Server

Caching
 GET can be cached while POST can't (safely)
 Specify max-age
– Use max-age cache control header
 Split data according to freshness requirement
 Separate private and public data
– Use private and public cache control header
 Support conditional GET
– Get if modified since
– E-tags

Media Types
• A resource can have different representations
– Ex: an image can be available as gif or jpeg
• Media types can be negotiated with HTTP
– Client can send Accept headers
• Prefer media types that lets you link resources
– Atom
– XHTML+Microformats

Some benefits of REST
 Faster response time (caching)
 Reduced server load (caching)
 Improved server scalability (no session state)
 Client software can be reused (uniform
interface)
 No separate resource discovery needed
(hyperlinks)
 Easy to serve different types of content such as
images, videos, xl-sheets etc.

“I think most people just make the
mistake that it should be simple to
design simple things. In reality, the
effort required to design something
is inversely proportional to the
simplicity of the result.”
- Roy Fielding

True!
Unless someone else has already
done the thinking for you

JAX-RS
• Simple URL mappings
• Simple media type specification
• Simple Cache-control header handling
• Simple HTTP response code handling
• Support when building URLs
• The REST is up to you :-)

JAX-RS Hello World
@Path(\"/helloworld\")
public class HelloWorld {
@GET
@Produces(\"text/plain\")
public String sayHello() {
return new String(\"Hello World!\");
}
}

JAX-RS
@Path(\"/slides\")
public class SlideResource {
Map<Slide> slides;
@GET
@Path(\"{id}\")
@Produces(\"text/html\")
public String getSlideAsHtml(@PathParam(\"id\") String slideId) {
return slides.get(slideId).getAsHtml();
}
...
}

JAX-RS
@Path(\"/slides\")
public class SlideResource {
Map<Slide> slides;
...
@PUT
@Path(\"{id}\")
@Consumes(\"application/json\")
public String save(@PathParam(\"id\") String slideId, String content) {
slides.put(slideId, new Slide(content));
return \"slide with id \" + slideId + \" stored\";
}
}

Describing the interface
 REST services should be self-descriptive
 Client can use HTTP OPTIONS command
 Content-type headers
 Links let the client navigate the API
 In theory no description language should be
needed
 There are some description languages though
 WADL
 WSDL2.0

PUT or POST?
 New resources could be created by either PUT
or POST
 Use PUT to create or edit a resource at a
known URL
 Use POST to create a resource and let the
server decide the URL

For the interested

For the interested
 Roy Fieldings PhD dissertation, see ch 5
– http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
 Roy Fieldings blog
– http://roy.gbiv.com/untangled/
 Mark Hadleys blog
– http://weblogs.java.net/blog/mhadley/
 Mark Nottinghams blog
– http://www.mnot.net
 Stefan Tilkovs blog
– http://www.innoq.com/blog/st/