Building RESTful Web Services with Jersey

Matthew Turland

Senior Engineer - Synacor, Inc.

Who I Am

Who I Work For

Synacor Logo

Synacor Headquarters - Buffalo, NY

The Topic of the Hour



(Yes, the project's logo could use some work.)

Jersey is a reference implementation of JAX-RS
(JSR311, Java API for RESTful Web Services)

What We'll Cover

Maven in a Nutshell

Apache Maven

A Note About Versions

Generating a Starting Project

From a terminal, issue this command:

What's Happening

Good time to grab a cup of coffee

Base Project Structure

Entering the POM

Adding Jersey

Changing Target Java Version

Setting Main Class

Main Class

Alternative Deployment Methods

Application Example

Running the Project

Another good time to grab a cup of coffee

Trying Out the Project

Creating a Resource Class

Leading / isn't necessary for @Path annotations and will cause subresource console errors

Implementing a Resource Method

Trying Out Resource Method

Supporting Multiple HTTP Methods

Parameterized Paths

Individual Query String Parameters

Path and Query String Parameters as Collections

Individual Form Parameters

Form Parameters as a Collection

Individual Request Headers

Request Headers as a Collection


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

Fielding, Roy Thomas (2000). Architectural Styles and the Design of Network-based Software Architectures, Section 5.1.3. (Ph.D. thesis). University of California, Irvine.

Translation: Do not use cookies in a REST web service. Ever.

Simple Responses

More Complex Responses

Implementing a Resource List

Checking Responses

Retrieving a Resource List

Implementing Resource Creation

Creating a Resource

Implementing Resource Retrieval

Retrieving a Resource

Implementing Resource Metadata Retrieval

Retrieving Resource Metadata

Implementing Resource Updating

Updating a Resource

Implementing Resource Deletion

Deleting a Resource

Supporting Multiple Representations

Examples of responses:
  • 501 Not Implemented - unrecognized HTTP method
  • 404 Not Found - no matching @Path
  • 405 Method Not Allowed - matching @Path, but no matching HTTP method annotation
  • 406 Not Acceptable - matching @Path and HTTP method annotation, no matching @Produces
  • 300 Multiple Choices - matching @Path and HTTP method annotation, multiple matching @Produces

Setting Default Representations

Tip: To support the same types for all resources in an API ...

Implementing XML Representations

XML with JAXB - Data Structure

XML with JAXB - Implementation

This approach requires more code, but allows the data structure to be kept separate from code that allows it to be converted to and from XML.

XML with POJOs using JAXB

The User class in this example is the same, but does not use the @XmlRootElement annotation.

Adding JSON Support

JSON with JAXB - Data

This data structure class is identical to the one in the previous XML example aside from the specification of a root element name in the @XmlRootElement annotation. While it can be specified, it's not needed.

JSON with JAXB - Usage

This approach requires more code, but allows the data structure to be kept separate from code that allows it to be converted to and from XML.

Low-Level JSON Support


Implementing Caching with Dates

Caching with Dates - Miss

Caching with Dates - Hit

Implementing Caching with ETags

Caching with ETags - Miss

Caching with ETags - Hit


Authentication Example

Adding Testing Framework

Adding a Resource test

Simulating GET Requests

Simulating POST Requests

Simulating PUT Requests

Simulating DELETE Requests

If including a body in a DELETE request, this error will be displayed: com.sun.jersey.api.client.ClientHandlerException: HTTP method DELETE doesn't support output See Client client = ApacheHttpClient.create();

Parsing JSON Responses

Running Tests

API Metadata

REST Resources

This Slide Deck

Slides will be available after the conference at

Or just go to the Publications section of my site


Please rate my talk!

QR Code

That's All, Folks