REST and Jersey Introduction

Chris WintersPittsburgh Java User Group

21 April 2009

   

Did you update the URLs?

(slide 13: update with IP so people can access)

   

Anyone want to vent?

   

Who am I?

http://www.cwinters.com/ (not the male model) Dad of awesome two year­old Software Architect at Vocollect Healthcare Systems Most experience on very small teams AccuNurse: voice­assisted care for nursing homes We use many, many opensource libraries Not a REST expert, just very interested

   

REST

Representational State Transfer Defined in Roy Fielding dissertation One primary implementation to­date: web + HTTP Why the interest? Web: ubiquitous, scalable, enabling platform

   

HTTP Success

Text­based! Simple! Universal! Clients and servers aren't tightly bound

   

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

   

So? I'm not building Amazon

Simplicity Flexibility Evolvability Testability Discoverability ...all good things, not related to scaling

   

A few initial warnings

Resource­oriented very useful approach ...tough to purely implement with browsers ...and it requires some mind bending Still worthwhile! REST != HTTP (but we'll use it anyway) Show a good deal of code

   

Map

What is REST? REST in Java What is REST? REST in Java ...

   

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!

   

REST boiled down

Give every "thing" an ID Link things together Use standard methods Resources with multiple representations Communicate statelessly

(from Stefan Tilkov, awesome REST guy)

   

Our dorky little application

Notem: record notes, become group memory Potential: Dynamic notes (~~IRC bots)

   

Access Notem now!

Crude interface, but easy to navigate Web:http://10.4.13.146:8765

Data:http://10.4.13.146:8765/r/

Distribution:http://10.4.13.146:8765/notem-0.25.zip

Slides:http://10.4.13.146:8765/cwinters_rest.pdf

   

Notem resources

Resource = 'state with URI' (lots else too) Every note Every collection of notes  Initial workspace

   

Jersey intro

RI of JSR­311, Sun folks primary on team

Heavily reliant on annotations

Skeptical before, but I'm a believer!

   

Jersey Extensibility

Highly extensible @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) 

   

RBD #1: An ID for everything

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

   

'Routeable' identifier?

Most think of ID as primary key: 42 Maybe: table:ID Maybe: server:database:table:ID ...where 'server' lookup into local registry Even if that worked, what would it return?

   

URI works everywhere

Built on top of basic plumbing (DNS, hostnames) Protocol specification built­in (http://, ftp://) Abstraction built­in too:

what I want (URL) how to shuffle it around (HTTP) not how to fetch/generate

   

Common misconception: URI design

"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

   

RBD #1: Jersey help

Every resource has an enforced unique URI ...not much beyond that

   

RBD #2: Link things together

Use server­provided URIs as references Clients building URIs is a common mistake!  Limit URI templates to query­building hints HATEOAS

   

URI templates?

On server­side, hugely useful Declare variables from URI, map to method params Also available: regex matching

   

HATEOAS?

Hypertext As The Engine of Application State

RTF uses "the hypermedia constraint" instead

   

HATEOAS!

Server­controlled links define what clients can do You can move hosts! Shard data! Change URIs! And potentially all this without taking systems down

   

HATEOAS + refactoring

Refactoring another benefit of HATEOAS Client dependent on server for state transitions ...immediately change 

client behavior Seems simple, but 

we're just used to it Start simple, grow 

organically

   

Clients cannot assume resource structure!

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

Jersey: application.wadl

Ways to know you're not doing HATEOAS...

   

'REST endpoint'

“Here's the endpoint for our REST API” REST exposes resources many URIs Not actions via a few

   

URI scheme up front

“Here are all the URIs in our REST API” ...implies out­of­band info important to app flow  Client discover resources moving through system Publishing your URI structure is coupling

   

Clients parse URIs

“Here's the data you'll need from the URI” URI is opaque identifier Content of resource should be standalone Example: /blog/2009/04/20/my_hair_isnt_that_bad

Does content have date in it too? API forces client to parse URIs: more coupling

   

URIs name actions

Flickr API URIs name actions vs resources

/services/rest/?method=flickr.test.echo...

REST has uniform interface! (more later) Specifying methods/actions == RPC

   

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."

­ Roy Fielding, REST APIs must be hypertext driven

   

So bad about coupling?

Evolvability Dependencies on structure inhibits evolution Do you expose your database tables? Or your libraries? If you choose to, it's a trade­off ...just one that REST explicitly chooses differently

   

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

   

More HATEOAS

Lots of recent discussion on this: rest­discuss posts (including Solomon Duskis) Subbu: "On Linking" Craig McC on Sun Cloud API

   

Generating links

Underdeveloped area 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

   

RBD #2: Jersey Help

“...this is probably the hardest area. JAX­RS provides a bunch of ways to construct URIs but there is no such URI binding facility with a modeling API, such as JAXB.”

­ Paul SandozInfoQ announcement: JSR 311 Final

   

RBD #3: Use standard methods

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

   

Dangers of unsafe GET

"[The Alexa toolbar] logged into the administrative area and followed the 'delete' link for every entry," the admin says. "My dumb­ass boss still didn't want to uninstall Alexa ­­ could have strangled the man."­ Stupid user tricks 3: IT admin follies

   

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 catch­all, the 'process' method

   

Standard methods + idempotency

Method Purpose Idempotent? Safe?===================================================GET Retrieve representation Y YPUT Provide representation Y NPOST Create/extend resource N NDELETE Delete resource Y NHEAD GET minus body Y YOPTIONS Find methods for resource Y Y

   

Which does RPC-over-HTTP use?

Method Purpose Idempotent? Safe?===================================================POST Create/extend resource **N** **N**

   

Benefits of standard methods

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

   

Where are my methods? Constraint!

Yes, GET/PUT/DELETE/POST are constraints Ask anyone who writes: can sharpen focus Thinking in uniform 

methods key to ROA

   

Nouning verbs

One pattern for adapting action­centric designs is nouning verbs[1]

Canonical example: transactions Treat the transaction as a resource with status Reference the resource in your actions – client 

maintains application state! (more later) 

[1] Because “resourcing verbs” sounds too Office Space-y

   

Nouning Transactions

   

TMTOWTDI

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 Actions­as­resources takes a while, but useful

   

RBD #3: Jersey support

Awesome Annotations for all major HTTP methods @HEAD coming in JAX­RS 1.1

   

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

   

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.”

­ Ebenezer Ikonne

   

Avoiding evil

Great presentation by Steve Vinoski on RPC history discusses RPC issues

Summary: Avoid ...if remote looks local, you will eventually lose

   

Current distributed systems

Highly dependent on code generation, stubs Winds up treating 

data­over­wire as opaque  ...will be difficult to reuse 

on the same platform cross­platform? ha!

   

Defining service contracts

“Using a regular programming language to define supposedly abstract interfaces greatly increases the chances that language­specific constructs will leak into the contract.”

­ Steve Vinoski

   

Problems with remote calls

RPC should have high barrier to entry: it's hard!

Very tight coupling Synchronization required (pre­3.0 entity beans?) Restricted failure modes Closed protocol (typically) And...

   

Fallacies of distributed computing

1) The network is reliable.

2) Latency is zero.

3) Bandwidth is infinite.

4) The network is secure.

   

Fallacies of distributed computing

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

   

RPC hopes

System that solves problems inherent in distributed computing.

Examples Vinoski uses: REST and Erlang   Make explicit tradeoffs to work around limitations Echoing Fielding dissertation: it's all about tradeoffs

   

Focus on data!

All this means: you're pushing the problem to data. This is good! You wind up there anyway. 

   

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

   

RBD #4: Multiple representations

'Resource' is an abstract entity, a concept You only interact with representations With HTTP, content negotiation informs

   

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

   

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 

to control 

   

Representation communicates resource

Others we could use?

   

Representation communicates resource

audio/mpeg: output of TTS engine application/ssml+xml: Speech synthesis markup (so 

your TTS can speak the note) application/morse­code (madeup) Representations can be derived: not every one needs 

to be PUTable

   

Designing representations

Behooves you to use widely known media types "Get over the idea that your domain is a unique and 

special snowflake" See Bill de Hora 

"Snowflake APIs"

   

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 application state...”

­ Roy Fielding, REST APIs must be hypertext driven

   

RBD #4: Jersey support

Awesome Declare @Produces and @Accepts for class or 

methods Jersey parses Accept header and dispatches to the 

right one

   

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 additional state

   

MessageBodyWriter examples

byte[] ­> ByteArrayProvider Viewable ­> ViewableMessageBodyWriter ­> 

TemplateProvider JAXB­registered object ­> 

JSONJAXBElementProvider || XMLJAXBElementProvider

   

Brief digression on JAXB

Nifty technology! Tutorials focus on XML schemas and code 

generation Skip all that, basic use is pretty easy

   

Marshalling sucks

How many libraries? JiBX, XmlBeans, XStream... No silver bullet

Marshalling always sucks, anyone who says differently is selling you something

   

RBD #5: Communicate statelessly

“...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 the client.”

­ Roy Fielding, p.78­9.

   

Benefits of statelessness

Caching Scale out, not up Simple in some senses, not others

   

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?

   

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 customizations...

   

Shopping cart example

Assuming a fully featured client ...how might we design a RESTful shopping cart?

   

RBD #5: Jersey support

Really an implementation detail Jersey helps you DTRT, but you're free to break it

   

Why caching?

The fastest DB query is the one never executed Nearly all applications are read­mostly: optimize! Transparently­added caching even better (view 'Many intermediaries image') The network is not transparent

   

Faking statefulness (test)

Form data just key/value pairs Cookies just text HTTP Authentication just a header

   

'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

   

'Architectural Style'

Abstraction for component interaction An architecture reflects its environment ...but hard to compare those from different 

environments  It is not a set of defined messages

   

'Architecture Style'

Alan Dean: A style can be applied to many different architectures. An architecture can consist of many different styles.

   

Pieces of the Style

Client/Server (separation of concerns) Stateless communication Caching Uniform interface Layered system Code on demand

   

Style implications

You will not be buying a 'REST Toolkit' One level up from tools allows evaluation of fit for 

purpose 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."

­ Fielding

   

Other styles

POX: Plain old XML: not bad <em>a priori</em>, but, ... typically everything goes through POST (XML­RPC)

MEST ('processThis()', see Jim Webber for more) "Low REST" vs "High REST" (RTF says it's 

hogwash)

   

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

   

Thank you!

   

Resources on REST

Collected on my site, slides are terrible for this:http://www.cwinters.com/rest/

   

Attributions

Testudo Shrug Tinkertoy Sticks  I hate zombies Mike Tomlin (Gregory Shamus/Getty Images) I Hate Mondays