1. REST and Jersey Introduction
Pittsburgh Java User Group
21 April 2009
2. Did you update the URLs?
(slide 13: update with IP so people can access)
3. Anyone want to vent?
4. Who am I?
http://www.cwinters.com/ (not the male model)
Dad of awesome two yearold
Software Architect at Vocollect Healthcare Systems
Most experience on very small teams
AccuNurse: voiceassisted care for nursing homes
We use many, many opensource libraries
Not a REST expert, just very interested
Representational State Transfer
Defined in Roy Fielding dissertation
One primary implementation todate: web + HTTP
Why the interest?
Web: ubiquitous, scalable, enabling platform
7. HTTP Success, Deeper
Supports very simple + very complex apps
Lots of options to scale, not just single path
Stateless by default
...which means it's easy to test
Those aren't documents, they're resources!
...and a resource ~~ distributed object
8. So? I'm not building Amazon
...all good things, not related to scaling
9. A few initial warnings
Resourceoriented very useful approach
...tough to purely implement with browsers
...and it requires some mind bending
REST != HTTP (but we'll use it anyway)
Show a good deal of code
What is REST?
REST in Java
What is REST?
REST in Java
11. In the beginning...
"REST" was created looking back at HTTP
But the guy who created REST
also helped create HTTP
His dissertation is very readable!
12. REST boiled down
Give every "thing" an ID
Link things together
Use standard methods
Resources with multiple representations
(from Stefan Tilkov, awesome REST guy)
13. Our dorky little application
Notem: record notes, become group memory
Potential: Dynamic notes (~~IRC bots)
15. Notem resources
Resource = 'state with URI' (lots else too)
Every collection of notes
16. Jersey intro
RI of JSR311, Sun
folks primary on team
Heavily reliant on
Skeptical before, but
I'm a believer!
17. Jersey Extensibility
@Provider means: "Hey Jersey, plug this in!"
Examples: TemplateProvider, JAXB items
Contextual items can be injected with @Context
Contextual: UriInfo, HttpHeaders, Security
Interesting bit: getting contextual data down to
objects manipulated by other frameworks (JAXB)
18. RBD #1: An ID for
ID == URI
I == Identifier, L == Location
Globally unique, routeable identifier
They don't have to be pretty!
'Thing' can have broad meaning:
Collection of other things
Process that can report state
19. 'Routeable' identifier?
Most think of ID as primary key: 42
...where 'server' lookup into local registry
Even if that worked, what would it return?
20. URI works everywhere
Built on top of basic plumbing (DNS, hostnames)
Protocol specification builtin (http://, ftp://)
Abstraction builtin too:
what I want (URL)
how to shuffle it around (HTTP)
not how to fetch/generate
21. Common misconception: URI
"Hackable" URIs nice, not necessary
Only constraint is that they're unique
BDUF: Lay out entire URI scheme
Agile: Define as you go, refactor mercilessly
22. RBD #1: Jersey help
Every resource has an enforced unique URI
...not much beyond that
23. RBD #2: Link things
Use serverprovided URIs as references
Clients building URIs is a common mistake!
Limit URI templates to querybuilding hints
24. URI templates?
On serverside, hugely useful
Declare variables from URI, map to method params
Also available: regex matching
Hypertext As The Engine
of Application State
RTF uses "the hypermedia
Servercontrolled links define what clients can do
You can move hosts!
And potentially all this without taking systems down
27. HATEOAS + refactoring
Refactoring another benefit of HATEOAS
Client dependent on server for state transitions
Seems simple, but
we're just used to it
Start simple, grow
28. Clients cannot assume
Everything the client can do is created by server
Client and server can know beforehand about media
types and types of transitions
Different 'rel' types in 'link' element...
OPTIONS informs about allowed methods
Ways to know you're not doing HATEOAS...
29. 'REST endpoint'
“Here's the endpoint for our REST API”
REST exposes resources many URIs
Not actions via a few
30. URI scheme up front
“Here are all the URIs in our REST API”
...implies outofband info important to app flow
Client discover resources moving through system
Publishing your URI structure is coupling
31. Clients parse URIs
“Here's the data you'll need from the URI”
URI is opaque identifier
Content of resource should be standalone
Does content have date in it too?
API forces client to parse URIs: more coupling
32. URIs name actions
Flickr API URIs name actions vs resources
REST has uniform interface! (more later)
Specifying methods/actions == RPC
33. RPC + Coupling
"Today's example is the SocialSite
REST API. That is RPC. It screams RPC.
There is so much coupling on display that it
should be given an X rating."
REST APIs must be hypertext driven
34. So bad about coupling?
Dependencies on structure inhibits evolution
Do you expose your database tables?
Or your libraries?
If you choose to, it's a tradeoff
...just one that REST explicitly chooses differently
35. URIs and the real world
Easier to publish API that says "Send datablob A to
URI B and X will occur"
IMO REST client development, generic or
otherwise, still early days...
...you do what you can
36. More HATEOAS
Lots of recent discussion on this:
restdiscuss posts (including Solomon Duskis)
Subbu: "On Linking"
Craig McC on Sun Cloud API
37. Generating links
Componentize link generation?
Should a resource generate its own URI?
How to inject context (host/port) down?
Manipulate rules at runtime?
Example: Reference all Employee objects at host frodo
Example: ...all Buildings with area > 25000 to gondor
38. RBD #2: Jersey Help
“...this is probably the hardest area. JAXRS
provides a bunch of ways to construct URIs but
there is no such URI binding facility with a
modeling API, such as JAXB.”
InfoQ announcement: JSR 311 Final
39. RBD #3: Use standard
AKA, 'uniform interface'
Methods never vary based on resources
Key constraint that allows intermediaries to function
Google knows GET is safe, can spider your site
...except when it's not safe
40. Dangers of unsafe GET
"[The Alexa toolbar] logged into the
administrative area and followed the
'delete' link for every entry," the admin
says. "My dumbass boss still didn't
want to uninstall Alexa could have
strangled the man."
Stupid user tricks 3: IT admin follies
41. Methods have semantics
Key difference from RPC systems
HTTP defines what GET/PUT/DELETE mean
...on any resource
Idempotent: invoke multiple times with same effect
What will service.updateOrder() do if called twice?
What about service.takeOrder()?
POST is the catchall, the 'process' method
42. Standard methods +
Method Purpose Idempotent? Safe?
GET Retrieve representation Y Y
PUT Provide representation Y N
POST Create/extend resource N N
DELETE Delete resource Y N
HEAD GET minus body Y Y
OPTIONS Find methods for resource Y Y
43. Which does RPC-over-HTTP
Method Purpose Idempotent? Safe?
POST Create/extend resource **N** **N**
44. Benefits of standard
Original name of REST: HTTP Object Model
All objects on the web can be manipulated similarly
Implementation hiding: what language? what
model? who cares?
Generic invocation: no need to generate code for
actions, only data
45. Where are my methods?
Yes, GET/PUT/DELETE/POST are constraints
Ask anyone who writes: can sharpen focus
Thinking in uniform
methods key to ROA
46. Nouning verbs
One pattern for adapting actioncentric designs is
Canonical example: transactions
Treat the transaction as a resource with status
Reference the resource in your actions – client
maintains application state! (more later)
 Because “resourcing verbs” sounds too Office Space-y
47. Nouning Transactions
Instead of referencing the resource, maybe I could
POST different resources to the transaction?
...transaction resource could passthru resources
There are multiple ways to do it: that's the point
Actionsasresources takes a while, but useful
49. RBD #3: Jersey support
Annotations for all major HTTP methods
@HEAD coming in JAXRS 1.1
50. Sidetrack: Jersey resources
“How does Jersey discover my resources?”
Define Application which explicitly names
Tell Jersey to scan your package
Wire into your DI framework (Spring/Guice)
Also true of @Provider implementations
51. Enabling evil
“Granted the abstraction of this messaging
infrastructure led to bindings and dependencies
that we are trying to get out of today, but that
doesn't make RPC evil, it's the technologies and
'programming style' that resulted from RPC that
have become evil.”
52. Avoiding evil
Great presentation by Steve Vinoski on RPC history
discusses RPC issues
...if remote looks local, you will eventually lose
53. Current distributed systems
Highly dependent on code generation, stubs
Winds up treating
dataoverwire as opaque
...will be difficult to reuse
on the same platform
54. Defining service contracts
“Using a regular programming language to define
supposedly abstract interfaces greatly increases
the chances that languagespecific constructs will
leak into the contract.”
55. Problems with remote calls
RPC should have high barrier to entry: it's hard!
Very tight coupling
Synchronization required (pre3.0 entity beans?)
Restricted failure modes
Closed protocol (typically)
56. Fallacies of distributed
1) The network is reliable.
2) Latency is zero.
3) Bandwidth is infinite.
4) The network is secure.
57. Fallacies of distributed
5) Topology doesn't change.
6) There is one administrator.
7) Transport cost is zero.
8) The network is homogeneous.
More: Fallacies of Distributed Computing Explained
58. RPC hopes
System that solves problems inherent in distributed
Examples Vinoski uses: REST and Erlang
Make explicit tradeoffs to work around limitations
Echoing Fielding dissertation: it's all about tradeoffs
59. Focus on data!
All this means: you're pushing the problem to data.
This is good! You wind up there anyway.
60. Sending data
Historically representation tied to RPC system
IIOP, DCE, RMI, SOAP + XML
Instead, your data identified by media type
Allows you to separate concerns:
Library for processing media type
Library for moving data through logic
61. RBD #4: Multiple
'Resource' is an abstract entity, a concept
You only interact with representations
With HTTP, content negotiation informs
62. HTTP: Accept
Every request has an 'Accept' HTTP header
Useful tools for seeing this in browser
Useful tools for specifying from CLI
RESTful service provides appropriate representation
63. Representations in Notem
Three main ones, not applicable in all cases
text/html, application/xml, application/json
When using programmatic HTTP access it's easier
Others we could use?
audio/mpeg: output of TTS engine
application/ssml+xml: Speech synthesis markup (so
your TTS can speak the note)
Representations can be derived: not every one needs
to be PUTable
66. Designing representations
Behooves you to use widely known media types
"Get over the idea that your domain is a unique and
See Bill de Hora
67. Media types
“A REST API should spend almost all of its
descriptive effort in defining the media type(s)
used for representing resources and driving
REST APIs must be hypertext driven
68. RBD #4: Jersey support
Declare @Produces and @Accepts for class or
Jersey parses Accept header and dispatches to the
69. What's a valid return value?
No interface required
One known: javax.ws.rs.core.Response: status
+ cookies, etag, entity...
Others: try to match with MessageBodyWriter
...including list/array, though may be useful to have
explicit 'collection representation' to model
71. Brief digression on JAXB
Tutorials focus on XML schemas and code
Skip all that, basic use is pretty easy
72. Marshalling sucks
How many libraries? JiBX, XmlBeans, XStream...
No silver bullet
Marshalling always sucks, anyone who says
differently is selling you something
73. RBD #5: Communicate
“...communication must be stateless in
nature...such that each request from client to
server must contain all of the information
necessary to understand the request, and cannot
take advantage of any stored context on the
server. Session state is therefore kept entirely on
Roy Fielding, p.789.
74. Benefits of statelessness
Scale out, not up
Simple in some senses, not others
75. Different types of state
Client: Application state is 'where' you are
Server: Resource state is what you're manipulating
Possible to represent application state as resource?
76. Examples of state
Phone conversation: all 'application' state
Client/server app: server holds open transactions,
current 'screen', relies on open connection
Web app: current page of results, shopping cart,
current 'item' being worked on, GUI
77. Shopping cart example
Assuming a fully featured client
...how might we design a RESTful shopping cart?
78. RBD #5: Jersey support
Really an implementation detail
Jersey helps you DTRT, but you're free to break it
79. Why caching?
The fastest DB query is the one never executed
Nearly all applications are readmostly: optimize!
Transparentlyadded caching even better
(view 'Many intermediaries image')
The network is not transparent
80. Faking statefulness (test)
Form data just key/value pairs
Cookies just text
HTTP Authentication just a header
81. 'Architectural Style'
“An architectural style is a coordinated set of
architectural constraints that restricts the
roles/features of architectural elements and the
allowed relationships among those elements
within any architecture that conforms to that style.”
Roy Fielding, p. 13
82. 'Architectural Style'
Abstraction for component interaction
An architecture reflects its environment
...but hard to compare those from different
It is not a set of defined messages
83. 'Architecture Style'
A style can be applied to many different architectures.
An architecture can consist of many different styles.
84. Pieces of the Style
Client/Server (separation of concerns)
Code on demand
85. Style implications
You will not be buying a 'REST Toolkit'
One level up from tools allows evaluation of fit for
Fielding dissertation opens with reference to Monty
Python sketch :
"It might very well be the best slaughterhouse design ever
conceived, but that would be of little comfort to the
prospective tenants as they are whisked along hallways
containing rotating knives."
86. Other styles
POX: Plain old XML: not bad <em>a priori</em>,
... typically everything goes through POST (XMLRPC)
MEST ('processThis()', see Jim Webber for more)
"Low REST" vs "High REST" (RTF says it's
87. Now what?
Evolvability is underrated
Distributed systems are hard
Try it! Building even a small system will introduce
new 'resources' that you probably haven't thought of
Jersey is proof that JSRs can work
88. Thank you!
89. Resources on REST
Collected on my site, slides are terrible for this:
I hate zombies
Mike Tomlin (Gregory Shamus/Getty Images)
I Hate Mondays