Sydney Java Users Group - RESTful design explained

1. RESTful stuff
Michael Neale
Red Hat
twitter.com/michaelneale
www.michaelneale.net

2. What is REST
Representational State Transfer
(Roy Fielding)
Already in use
(Kinda) part of the web from day 1

3. What it is not
A protocol
An interface
An API
A drop in replacement for SOAP

6. REST is
An architectural style
Evolved with HTTP 1.1
Nice to use !

7. What is wrong with
SOAP?
Have to invent protocol (nouns,
verbs) for each “service”
Every service is different
BUT: you can generate stubs
Nice? or brittle?
Encourages RPC?
Is not Simple or about Objects

8. Many SOAP services end up doc-style
XML messaging
useless: eg MS Sharepoint “xs:any” as
payload !

9. What is right with
REST
Fixed well defined verbs: GET, PUT,
POST, DELETE, HEAD ...
Focus on resources (not services)
Different REST endpoints “feel
consistent”
Makes “service implementer” work
harder

10. Stupid Example
The stock ticker

12. Oh FFS

13. REST
GET https://service/quote/AAPL

14. Subtleties
Content type returned (content type
negotiation)
What do you do with your spare time?

15. Focus is on data
Not services
So not a drop in for SOAP/RPC
Sometimes people do XML/RPC (but is
not RESTful)
Sometimes that is cool
Can use XSDs for this
WADL is silly

16. JAX-RS
javax.ws.rs
annotations to define paths/resources
on POJOs
Implementations: RESTEasy, Jersey
Part of EE6 (I think??) not web (??)

17. JAX-RS
Runs in servlet container
use @Path to annotate url paths to
POJOs
container will create if needed
Config in web.xml... boring...

18. Sorry
All my real world examples are in
scala

20. GET http://myhost.com/services/
library/books
GET http://myhost.com/services/
library/book/333
PUT http://myhost.com/services/
library/book/333
DELETE http://myhost.com/services/
library/book/333

22. Content Negotiation

23. In Theory...
Annotate pojos
but in practice: tend to tailor for
REST
Use Response object
Helper methods
Still easy

24. Some more theory
GET, PUT, DELETE meant to be idempotent
POST is powerful (and easily abused)
Use HTTP standard headers
Accept (content)
ETags for cache control
Lots are in HTTP (frameworks help you
out)

25. Content type
http://www.iana.org/assignments/
media-types/
Media types (MIME types) important
for payloads
eg application/json, text/html etc
Use content negotiation to select
appropriate for client

26. Useful formats
JSON
XML (XSD?)
x-www-form-urlencoded (for name/value
pairs)
html (can just be collection of
links !)

27. Content negotiation
Simple theory:
Client sets Accept (with
preference)
Server (jax-rs) uses @Produces
Are other ways
Complex to hand-roll

28. Client side
No specific dependencies
Just a http client
Sometimes can generate stubs
but would need XSDs etc
RESTEasy has some tools

31. Web clients
Can use direct from ajax
Modulo support for PUT, DELETE
Or treat the web view tier as
“client” to RESTful api

32. HATEOAS
Hypermedia as the engine of
application state
Basically: use links when GET:
<link href=’/someotherresource’/>
Should only have one entry point
(URL) and rest discovered (via links
- hypermedia !)
Honour Accept header/media types

33. No client side URL
construction
GET deltacloud/api -->

34. Sitebricks
jax-rs/RESTEasy to heavy for some
some design mistakes
As it is a spec, we are SOL
So consider sitebricks (shit bricks?)

36. Can everything fit
In RESTful design?
Probably not.
XML-RPC sometimes handy
SOAP is overkill, always.

37. Thanks
http://jboss.org/resteasy
http://code.google.com/p/google-
sitebricks/