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
Top Related