Bright Java Tutorial

is brought to you by DoITBright LLC

REST Web Service

JAX-RS HTTP GET Example of REST Web Service

JAX-RS is a Java API specification that provides support in creating or developing RESTful web services. In this lesson, we will be creating a simple RESTful web service that is accessible via HTTP GET method and is implemented via JAX-RS. Before we can actually start our development, we need to setup our environment. Here are the things that you will need to do.


Using your Eclipse IDE, create a 'Java Project' and name it as 'RestJumpStart'. Configure your 'Build Path' as follows...

REST Eclipse Build Path


Extract the Jersey ZIP file that you have downloaded. At the time of this writing, I hav jaxrs-ri-2.23.2.zip and upon extracting the files, I now have a directory and file structure like this...

Download Jersey ZIP


Copy all the JAR files that can be found in the 'api', 'lib' and 'ext' directories inside the '/jaxrs-ri-2.23.2/jaxrs-ri' directory and paste it on your '/RestJumpStart/WEB-INF/lib' directory. Then, make sure you add those JAR files in the 'Build Path' of your Eclipse project.

REST Eclipse Libraries Build Path


Now that you have your environment set up, we can now start developing our RESTful web services. Our first example is a web service that allows us to retrieve all 'Accounts' in an XML format. This REST web service will be accessible via the HTTP GET method. Create a package and name it as 'com.rest.service'. Inside that package, create a Java class and name it as 'AccountService'.

  package com.rest.service;

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

  @Path("/AccountService")
  public class AccountService {

    @GET
    @Path("/accounts")
    @Produces(MediaType.APPLICATION_XML)
    public String getAccounts(){
      return "<accounts><account><accountId>1</accountId>" 
        + "<firstName>Rolan</firstName>" 
        + "<lastName>Liwanag</lastName>" 
        + "</account></accounts>";
    }
  }
                            

As you can see, our example is very simple and straight forward. On top of our 'AccountService' class, we placed an annotation '@Path("/AccountService")' which simply means, this resource is accessible via the path 'AccountService' appended to the base path. The next thing we need to do is create our deployment descriptor which is the 'web.xml' file.

  <?xml version="1.0" encoding="UTF-8"?>
  <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://java.sun.com/xml/ns/javaee"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
      http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
      id="WebApp_ID" version="3.0">
    <display-name>Rest Jump Start</display-name>
    <servlet>
      <servlet-name>
        Jersey RESTful Application
      </servlet-name>
      <servlet-class>
        org.glassfish.jersey.servlet.ServletContainer
      </servlet-class>
      <init-param>
        <param-name>
          jersey.config.server.provider.packages
        </param-name>
        <param-value>
          com.rest.service
        </param-value>
      </init-param>
    </servlet>
    <servlet-mapping>
      <servlet-name>
        Jersey RESTful Application
      </servlet-name>
      <url-pattern>
        /rest/*
      </url-pattern>
    </servlet-mapping>
  </web-app>
                            

Please take note that the URL pattern is '/rest/*'. Our directory and file structure will finally look like this...

REST Eclipse Directory and File Structure


Deploy your application by copying your 'RestJumpStart' directory to your '/tomcat/webapps/' directory. Then, open a command prompt and start your Apache Tomcat application server. You can now invoke your RESTful web service by opening your favorite browser and pasting the 'http://localhost:8080/RestJumpStart/rest/AccountService/accounts' at the URL bar and hit the 'Enter' button. Let us figure out how we arrived at this kind of URL for our RESTful application. 'RestJumpStart' is our application name. So it is natural that it will be appended next to 'http://localhost:8080'. In our 'web.xml', we specified a URL pattern of '/rest/*'. This gets appended after the application name. Then, our 'AccountService' class has an annotation path that points to 'AccountService'. This means, if we wish to refer to this class, we must appened 'AccountService' to the URL. Last but not the least, we specified that the method 'getAccounts' is accessible via HTTP GET method and appending 'accounts' at the URL.


Next