rest
DESCRIPTION
Presentation about the basic principles in RESTTRANSCRIPT
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/