Building RESTful Services with Java Using JAX-RS and Jersey — Sample Application

I’m working on a project that required a RESTful API implemented in Java. Jersey, the reference implementation for JAX-RS, made it easy to implement and deploy these services. I figured I’d share my sample application here.

Configuring Tomcat (or your own app server)

There are many options to initialize Jersey in your servlet container. Some of them require no XML configuration at all. For my application, I simply configured the Jersey Servlet in web.xml as follows:

<servlet>
	<servlet-name>Jersey</servlet-name>
	<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
	<init-param>
		<param-name>com.sun.jersey.config.property.packages</param-name>
		<param-value>org.coenraets</param-value>
	</init-param>
	<load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
	<servlet-name>Jersey</servlet-name>
	<url-pattern>/rest/*</url-pattern>
</servlet-mapping>

NOTE: Using this type of initialization, the packages parameter defines which classes Jersey will scan for URL Paths to resolve: in this case, all the classes in org.coenraets.* packages.

Defining the REST API

Before working on the implementation, I identified that my simple application would require three services:

1. Find all employees
2. Find an employee by id
3. Find a list of direct reports for a specific employee

Based on these requirements, I came up with the following REST API:

1. /api/employees
   Returns all employees
2. /api/employees/1
   Returns an employee identified by id (employee 1 in this case)
3. /api/employees/1/reports
   Returns direct reports of an employee (employee 1 in this case)

Implementing the API

Once my API was defined, providing the implementation using JAX-RS was easy. I just created a Java class defined as follows:

package org.coenraets.directory;

import java.util.List;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("/employees")
public class EmployeeResource {

	EmployeeDAO dao = new EmployeeDAO();

	@GET
	@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
	public List<Employee> findAll() {
		return dao.findAll();
	}

	@GET @Path("{id}")
	@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
	public Employee findById(@PathParam("id") String id) {
		return dao.findById(Integer.parseInt(id));
	}

	@GET @Path("{id}/reports")
	@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
	public List<Employee> findByManager(@PathParam("id") String managerId) {
		return dao.findByManager(Integer.parseInt(managerId));
	}
}

You annotate your class and methods with the path (@Path) and the content type (@Produces) they respond to. The serialization from model objects to the content type requested by the client happens automatically. In this application, the methods will return either JSON or XML depending on the content type requested by the client.

The approach you use to actually retrieve the data is, of course, totally up to you. In this example, I use a simple DAO, but you can of course use your own data access solution.

This application only required GET methods, but JAX-RS allows you to handle the other HTTP methods (@GET, @PUT, @POST, @DELETE and @HEAD).

Note that the package name matches the packages parameter defined in web.xml.

Testing the API

If you want to test your API before using it in a client application, you can invoke your REST services straight from a browser address bar. For example, try:

http://coenraets.org/rest/employees
http://coenraets.org/rest/employees//1
http://coenraets.org/rest/employees/1/reports

However, that doesn’t give you full control to test all the content types your API can return. A common option to test the different content types supported by your API is to use cURL and specify the content type requested in the Accept header:

curl -I http://coenraets.org/rest/employees -H’Accept:application/json’

Download the Source Code

Click here to download the source code (Eclipse Dynamic Web Project).

In my next post, I’ll share the client-side of the application: how to invoke these services using jQuery (and JSON).