RESTful Web Services using JAX-RS & Jersey

byBrian Gilstrap

Friday, November 13, 2009

A bit about REST

REpresentational State Transfer

Architectural approach, not a framework

Follows the ‘regular’ web (web pages)

Only a few verbs (GET,PUT,POST,DELETE*)

*a few others like HEAD

Friday, November 13, 2009

What about objects?

Java objects have other verbs:‘reserveSeat’, ‘makeReservation’, etc.

How to map these to REST?

The short answer: expose more resources

e.g. ‘SeatReservation’ resource replaces ‘reserveSeat’ and ‘cancelSeatReservation’ methods

Friday, November 13, 2009

Our example

Information about CDs

Artists, Albums, Tracks

An artist has albums

Albums have tracks

String nameSet<Album> albums...

Artist

*1String nameArtist artistSet<Track> tracks...

Album

String nameAlbum album...

Track

*

1

[Query methods]Artists

*

*

[Query methods]Albums

[Query methods]Tracks

*

*

**

Friday, November 13, 2009

Our Example (2)

Core Model

Java POJOs

Using Hibernate to access:

An HSQLDB database

Needs to be exposed as a Web Service

Friday, November 13, 2009

Building our RESTful Service

? Design our URL scheme

? Startup for the web service

? Annotate resource methods

? Implement any code to convert

Friday, November 13, 2009

What URL scheme to use?

? http://myhost/music?artist=Thomas%20Dolby

? http://myhost/music/artists/Thomas%20Dolby

? http://myhost/music/artist/235768

? http://myhost/music?album=The%20Flat%20Earth

? http://myhost/music/artists/Thomas%20Dolby/The%20Flat%20Earth

? http://myhost/music/albums/The%20Flat%20Earth

? etc.

Should we use query params?

Should we use the unique identifier for the artist?

What about duplicates?

What if we rename to “Dolby, Thomas”?

What if we rename to “Dolby, Thomas”?

Friday, November 13, 2009

What would REST suggest for URLs?

Avoid queries except for actual queries.

Resources can be either human-readable or not

if you use human-readable names, what do you do when things are renamed?

Can use id’s as canonical URLS and names as a convenience

Friday, November 13, 2009

Our URL Scheme

Sensible hierarchy

e.g. artists under “.../artists/...”

A way to address a particular resource

A way to address sub-resources

A way to list all of a particular kind of resource

A way to search for resources

Need:

Friday, November 13, 2009

Our Hierarchy

Paths to various kinds of resources

/artists/...

/albums/...

/tracks/...

Friday, November 13, 2009

Retrieving a Single Resource

/artists/id/{Artist ID} - a particular artist

/artists/{Name} - looks for an artist with that name and sends a forwarding to the proper /artists/id/{id}

/albums/id/{Album ID} - a particular album

/tracks/id/{Track ID} - a particular track of a particular album of a particular artist

Friday, November 13, 2009

Searching/artists?searchType=STARTS&searchString=F

“Find all artists whose name starts with ‘F’.”

searchType is one of IS, STARTS, CONTAINS, ENDS

/albums?searchType=STARTS&searchString=F

/tracks?searchType=IS&searchString=The%20Christmas%20Song

Return zero or more URL’s for matching resources

Friday, November 13, 2009

HTTP Refresher

HTTP requests have

Verb: (GET,PUT,POST,DELETE)

URL

Headers

Body

Friday, November 13, 2009

What about creating/updating/deleting?

We use normal HTTP verbs

GET - retrieve a representation

POST - create a resource

PUT - update a resource

DELETE - delete a resource*

POST is appropriate when using unique IDs (not names)

in your URIs

*With some hacks to aid browsers (they can’t generate DELETE)

Friday, November 13, 2009

Creating a resourcePOST

Request body contains representation of resource

URI is based on what is being created

/artists - create an artist

/albums - create an album

/tracks - create a track

e.g. POST /artists - no ID specified since system will assign it.

Friday, November 13, 2009

Updating a resource

PUT

Request body contains changes

Can be a partial update (only updating some parts of the resource)

Can be a full update (all state of resource specified)

e.g. PUT /artists/352 - to update info on Thomas Dolby

Friday, November 13, 2009

Deleting a resource

DELETE

No body required

e.g. DELETE/artists/352 - delete Thomas Dolby and all sub-resources (his albums and their tracks).

Friday, November 13, 2009

Intro to the Code

Object Model

Grizzly web container

Jersey

Friday, November 13, 2009

Jersey integrates well

Spring

Spring annotations

JSON - via jettison

JAXB

JSON-via-JAXB

WADL

HTTPS - via javax.net.ssl

JAAS

Ajax apps - via jMaki and JSONP

ATOM - abdera

etc.

“Plays well with others”

Friday, November 13, 2009

ResourcesREST

Wikipedia: http://en.wikipedia.org/wiki/REST

Roy Fielding’s Dissertation: "Principled Design of the Modern Web Architecture" http://www.ics.uci.edu/~taylor/documents/2002-REST-TOIT.pdf

RESTFul Web Services:

http://oreilly.com/catalog/9780596529260/

Friday, November 13, 2009

Resources (2)Jersey

https://jersey.dev.java.net/

https://jersey.dev.java.net/documentation/1.1.0-ea/user-guide.html

JAX-RS Specification

https://jsr311.dev.java.net/

http://jcp.org/en/jsr/summary?id=311

My Blog Posts introducing JAX-RS and Jersey

http://viewfromthefringe.blogspot.com/2009/06/jax-rs-and-jersey-posts.html

Friday, November 13, 2009

Other Frameworks

JBoss RESTEasy - http://www.jboss.org/resteasy/

Apache CXF - http://cxf.apache.org/

mixed with support for JAX-WS & WS-*

Restlet - http://www.restlet.org

Apache wink - http://incubator.apache.org/wink/ (1.0 just released Nov 9th)

Friday, November 13, 2009

Questions?

Friday, November 13, 2009