REST

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

Attribution: Paul Downey http://blog.whatfettle.com

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

ServerClient

GET http://bjarlestam.com/slides

[slide1, slide2, slide3, slide4]

GET http://bjarlestam.com/slides/getSlide?id=slide1

With linking

ServerClient

GET http://bjarlestam.com/slides

[ http://bjarlestam.com/slides/slide1, http://bjarlestam.com/slides/slide2, http://bjarlestam.com/slides/slide3, http://bjarlestam.com/slides/slide4 ]

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

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

Stateful

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

Stateless

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

ProxyCache

Client

Client

Server

ProxyCache

Client

ReverseProxyCache

ClientCache

ClientCache

ClientCache

ClientCache

“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!");

}

}

@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";

}

}

JAX-RS

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/