Quick and Simple RESTful web service example with Jersey

What is Jersey?
Jersey is a implementation of JAX-RS which is a standard for RESTful Web Services.

Why Jersey is needed when creating RESTful web services?
Jersey is not a must when creating RESTful web services. But Jersey makes our lives easier when creating RESTful services. Below tutorial will show you how.

First create a new web project and name it as RestExample.
Download and add asm-all-x.x.x.jar and jersey-bundle-x.x.x.jar to your project.

Configure the Jersey ServletContainer in your web.xml as below.

<?xml version="1.0" encoding="UTF-8"?>
<web-app .....>
  <servlet>
   <servlet-name>jersy-servlet</servlet-name>
   <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
   <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
   <servlet-name>jersy-servlet</servlet-name>
   <url-pattern>/*</url-pattern>
  </servlet-mapping>
</web-app>

Note that all the requests match the above configured url pattern(/*) are sent through the Jersey ServletContainer and if any of them matches with a url pattern of a registered web service(@Path) Jersey point the request to that service.
Now you are ready to create your first RESTful web service with Jersey. Create a new java class and name it as UserManagementService. Now change your class as below and your web service is ready.

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Response;

@Path("/user")
public class UserManagementService {
@GET
@Path("/profile")
@Produces("application/xml")
public Response getUserProfile() {
String retVal = "<user>" +
                  "<username>John</username>" +
                  "<email>john@example.com</email>" +
                "</user>";
return Response.status(200).entity(retVal).build();
}
}

This simple web service returns a user profile in xml format.
Enter below url in your browser.
http://localhost:8080/RestExample/user/profile

You will get below result.

Note that the annotations are the most important part which convert your plain java class in to a RESTful web service. Those are explained below.

@Path("/user") - If a request url matches this pattern Jersey redirects the request to this class.
@Path("/profile") - If a request redirected to this class matches the pattern "/profile", this method is responsible to serve the request.
@GET - Indicates that this method supports HTTP GET requests. Similarly other valid annotations are " @POST, @PUT, @DELETE and @HEAD". Note only one of these annotations can be applied for one method.
@Produces - This is the response type of this service. This is set as the Content-Type header of the http response. As you know this is used by the browsers to render the output.

Following annotations are also frequently used.

@Consumes - This can be used to specify the media types that can be consumed by the service.
@QueryParam - This is used to extract query string parameters from the request URL.
@PathParam - This is used to get data from request url.

Below is a simple web service which uses @QueryParam,  @PathParam and @HeaderParam annotations.

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.HeaderParam;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.Response;

@Path("/hello")
public class HelloService {
 @GET
 @Path("/{firstname}/{lastname}")
 @Produces("text/plain")
 public Response getWelcomeMessage(@QueryParam("company") String company,
                                                        @PathParam("firstname") String firstName, 
                                                        @PathParam("lastname") String lastName
                                   @HeaderParam("Authorization") String token) {
  System.out.println("Auth token is " + token);
 String retVal = "Welcome to " + company + " " + firstName + " " + lastName;
  return Response.status(200).entity(retVal).build();
 }
}

Enter below url in your browser and see the result.
http://localhost:8080/RestExample/hello/John/Daniel?company=ABC

The output will be as below.