March 02, 2009

Building RESTful web service using Jersey

Jersey is an open source reference implementation of JSR-311. The implementation provides support for annotations defined in JSR-311 and other APIs making it easy for developers to build RESTful web service. In this tutorial we will build a simple Hello World web service using Jersey.

Before we code, let’s have a look at basics.

What is a RESTful web service?

Representational state transfer (REST) is a style of software architecture for distributed hypermedia systems. It’s not a standard but makes use of widely accepted standards like HTTP,HTML, XML and URL.

A client application using REST is viewed as state machine. The client references a Web resource using a URL. A representation of the resource called is returned to the client. It can be HTML, XML, plain text etc.

What is Jersey?

Like I earlier - Jersey is the open source JAX-RS (JSR 311) reference implementation for building RESTful web services. Jersey 1.0.2 implements JAX-RS 1.0 and is shipped with GlassFish server. You can download the jars from Jersey site:

Building our frist RESTful web service

I have kept our first web service as simple as possible. It would just serve a text “Hello World”! You can grab the source code here. I have used ServletContainer to expose the service. This way you will be able to deploy our service in any servlet container.

In REST, a service is called resource. Jersey provides annotation what make developers job easy and quick. Here is our resource (
package rest.resource;

public class HelloWorldResource {

public String getMessage() {
return "Hello World";
Remove the annotations and you get a simple POJO. So, in short what we are doing here is adding some annotations to a POJO and deploying it as a service. Let me explain the annotation you see in the above code.

@Path defines a relative URI path for accessing the service. What you see is a very simple path. JAX-RS allows you to embed variables in URI making it path templates.

@GET annotation designates the request method. JAX-RS supports @POST, @PUT, @DELETE and @HEAD along with @GET method.

@Produces annotation is used to specify the MIME types for a resource representation that is sent back to the client. In our case, we are returning a plain text.

We will discuss other annotation is the coming tutorials. With this, we have out first service ready. To deploy this in a servlet container we need to configure web.xml to process requests coming to the server. In web.xml file, we declare a serlvet-class with appropriate parameters as shown below:
Please note that in my servlet-mapping, I have the url-pattern as /jersey/*. This is not the only method to specify REST resources class in web.xml. I will explain other methods in a separate article.You can access our new RESTful service using the URL http://localhost:8080/restweb/jersey/helloworld.


Roby said...
This comment has been removed by the author.
Roby said...

Abdel, the blog was useful for me to understand and run a simple web-service.

It is a really good endeavor by you so early in your career.

Keep up the good work.