Spring REST Tutorial

I’ve just written an updated tutorial for building a RESTful services with Spring Boot. Have a look here.

In this post I’ll show you how to implement a RESTful web service using the Spring framework. REST support was introduced as part of Spring 3 and is built on top of the existing Spring MVC stack, so anyone that has worked with Spring MVC in the past should find the REST support very easy to grasp. I’ll provide a step by step guide so even if you’re not familiar with Spring MVC you should be able get a RESTful service up and running quickly.

What is REST?

REST is an architectural style that has evolved from existing web technologies to allow client applications to communicate with a server using a simple and familiar approach. The approach is familiar because REST is built on top of the HTTP protocol, a protocol that has formed the backbone of the web for years. REST leverages the existing capabilities of HTTP and uses them to provide an architectural approach for implementing a simple and effective client server model.
This formal definition of REST and what constitutes pure RESTful behaviour is well beyond the scope of this blog. It’s definitely something that’s worth discussing so I’ll be posting on this topic pretty soon. For now though I’ll take you through the process of building, deploying and testing a simple RESTful service using the Spring framework.

Tech Stack

The sample REST API will be built using the following technology stack.

• Spring MVC 3.1
• Maven
• Tomcat

It is assumed that readers have a basic knowledge of the technologies listed above. To help you get up and running as quick as possible I’ll attach the full project so that you can download and import it into STS (or Eclipse).

Creating a Project Skeleton

We’ll start off by creating a basic Spring web project. You can either create it by hand or use something like Maven or Spring Roo to generate the basic project structure for you. Given the simplicity of our sample application you will probably create it by hand. Figure 1.0 below shows what the project structure should look like.

Figure 1.0 – Project Structure

The main project components are described below.

• src/main/java folder – this folder structure will contain all java source required by your project. This includes the MVC controller that will process REST requests and a few other bits and pieces we’ll cover later.
• src/main/resources folder – this folder structure will contain all resources required by your project. This could contain any number of configuration files in an enterprise application but given the simplicity of our demo app we’ll just have the log4j configuration here.
• META-INF/context.xml – this file contains resources that can be used by Tomcat at runtime. This file is empty in our sample application but in an enterprise application would contain JNDI references to any number of enterprise resources (data sources, MQ managers etc)
• rest-services-config.xml – this file contains definitions for the various Spring beans required by our application. This will be covered in detail later.
• Web.xml – This file is the base configuration for our java web application and is required as part of the standard Java Servlet specification. It is used to bootstrap the application on server start up and contains references to any Servlets or filters required by the application. This will be covered in detail later.
• POM.xml – this is our Maven configuration and contains information necessary to resolve dependencies (external libraries) and build a deployable WAR file.

Once you have the above project skeleton in place you’ll need to start configuring the application. We’ll start off with Web.xml which is shown below. I’ve commented each section to explain exactly what is being configured and how it impacts the application.

<?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"  
           xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"  
           xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web
           id="WebApp_ID"  
           version="2.5">  
     
      <display-name>REST Sample</display-name>  
     
      <!--  
           Main configuration file for this Spring web application.  
      -->  
      <context-param>  
           <param-name>contextConfigLocation</param-name>  
           <param-value>  
                /WEB-INF/config/rest-services-config.xml  
           </param-value>  
      </context-param>  
      
      <!--  
           Loads the Spring web application context using the config file defined above.  
      -->  
      <listener>  
           <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>  
      </listener>  
      
       <!--  
           Define the Spring Dispatcher Servlet for the REST services.  
           The 'contextConfiguration' param with an empty value means that the  
           Spring Context won't try to load a default file called restservices-servlet.xml  
       -->  
      <servlet>  
           <servlet-name>restservices</servlet-name>  
           <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>  
           <init-param>  
                <param-name>contextConfigLocation</param-name>  
                <param-value></param-value>  
           </init-param>  
           <load-on-startup>1</load-on-startup>  
      </servlet>  

      <!--  
           This Servlet mapping means that this Servlet will handle all incoming requests  
       -->  
      <servlet-mapping>  
           <servlet-name>restservices</servlet-name>  
           <url-pattern>/</url-pattern>  
      </servlet-mapping>  
 </web-app>

Next we’ll set up rest-services-config.xml the content of which is shown below. I’ve commented each section to explain exactly what is being configured and how it impacts the application.

<?xml version="1.0" encoding="UTF-8"?>  
 <beans xmlns="http://www.springframework.org/schema/beans"  
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
           xmlns:oxm="http://www.springframework.org/schema/oxm"  
           xmlns:util="http://www.springframework.org/schema/util"  
           xmlns:mvc="http://www.springframework.org/schema/mvc"  
           xmlns:context="http://www.springframework.org/schema/context"  
           xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd  
                                    http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-3.0.xsd  
                                    http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd  
                                    http://www.springframework.org/schema/oxm  
                                    http://www.springframework.org/schema/oxm/spring-oxm-3.0.xsd  
                                    http://www.springframework.org/schema/util  
                                     http://www.springframework.org/schema/util/spring-util-3.0.xsd">  
      <!--  
            Enables automatic mapping of fund objects to and from JSON  
      -->  
      <mvc:annotation-driven/>  
      <!--  
            Setup spring to pull in @Controller, @RequestMapping, etc Configuration scans specified packages  
            for classes configured as Spring managed beans and automatically sets up objects annotated with  
            @Controller, @Service etc.  
      -->  
      <context:component-scan base-package="com.blog.samples.webservices.rest" />  
      <context:component-scan base-package="com.blog.samples.services" />  
      <bean class="org.springframework.web.servlet.mvc.annotation.DefaultAnnotationHandlerMapping" />  
      <!--  
            Configures view for returning JSON to the client  
      -->  
      <bean class="org.springframework.web.servlet.view.json.MappingJacksonJsonView">  
           <property name="contentType" value="text/plain"/>  
      </bean>  
      <!--  
            maps handler methods based on HTTP paths
      -->  
      <bean class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter">  
           <property name="messageConverters">  
                <util:list id="beanList">  
                     <ref bean="jsonMessageConverter"/>  
                </util:list>  
           </property>  
      </bean>  
      <!--  
            Converts JSON to POJO and vice versa  
      -->  
      <bean id="jsonMessageConverter" class="org.springframework.http.converter.json.MappingJacksonHttpMessageConverter"/>  
 </beans>

The final part of the project skeleton is our maven POM file. This contains build and dependency details for our application and is defined below.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0                                       http://maven.apache.org/maven-v4_0_0.xsd">
   <artifactId>rest-sample</artifactId>
   <modelVersion>4.0.0</modelVersion>
   <inceptionYear>2011</inceptionYear>
   <packaging>war</packaging>
   <groupId>com.blog.rest</groupId>
   <version>1.0</version>
   <properties>
      <releaseCandidate>1</releaseCandidate>
      <spring.version>3.1.1.RELEASE</spring.version>
      <java.version>1.5</java.version>
      <jackson.mapper.version>1.5.6</jackson.mapper.version>
      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
      <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
      <maven.javadoc.reporting.version>2.7</maven.javadoc.reporting.version>
      <commons.logging.version>1.1.1</commons.logging.version>
      <log4j.version>1.2.16</log4j.version>
      <context.path>rest-sample</context.path>
      <jackson.mapper.version>1.5.6</jackson.mapper.version>
   </properties>
   <build>
      <resources>
         <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering>
         </resource>
      </resources>
      <plugins>
         <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-war-plugin</artifactId>
            <configuration>
               <warName>${context.path}</warName>
            </configuration>
         </plugin>
      </plugins>
   </build>
   <dependencies>
      <dependency>
         <groupId>log4j</groupId>
         <artifactId>log4j</artifactId>
         <version>${log4j.version}</version>
      </dependency>
      <dependency>
         <groupId>org.springframework</groupId>
         <artifactId>spring-core</artifactId>
         <version>${spring.version}</version>
      </dependency>
      <dependency>
         <groupId>org.springframework</groupId>
         <artifactId>spring-context</artifactId>
         <version>${spring.version}</version>
      </dependency>
      <dependency>
         <groupId>org.springframework</groupId>
         <artifactId>spring-beans</artifactId>
         <version>${spring.version}</version>
      </dependency>
      <dependency>
         <groupId>org.springframework</groupId>
         <artifactId>spring-aop</artifactId>
         <version>${spring.version}</version>
      </dependency>
      <dependency>
         <groupId>org.springframework</groupId>
         <artifactId>spring-aspects</artifactId>
         <version>${spring.version}</version>
      </dependency>
      <dependency>
         <groupId>org.springframework</groupId>
         <artifactId>spring-asm</artifactId>
         <version>${spring.version}</version>
      </dependency>
      <dependency>
         <groupId>org.springframework</groupId>
         <artifactId>spring-expression</artifactId>
         <version>${spring.version}</version>
      </dependency>
      <dependency>
         <groupId>org.springframework</groupId>
         <artifactId>spring-web</artifactId>
         <version>${spring.version}</version>
      </dependency>
      <dependency>
         <groupId>org.springframework</groupId>
         <artifactId>spring-webmvc</artifactId>
         <version>${spring.version}</version>
      </dependency>
      <dependency>
         <groupId>org.codehaus.jackson</groupId>
         <artifactId>jackson-mapper-asl</artifactId>
         <version>${jackson.mapper.version}</version>
      </dependency>
      <dependency>
         <groupId>javax.servlet</groupId>
         <artifactId>servlet-api</artifactId>
         <version>2.4</version>
      </dependency>
   </dependencies>
</project>

At this point you should have a project skeleton in place and it should look like the workspace in figure 1.0.

Defining a Domain Object

This sample application will expose a series of RESTful methods that allow client applications to perform operations on Funds. Our fund object is a very simple POJO and is defined as follows.

package com.blog.samples.domain;  

import java.util.Date;  
import org.codehaus.jackson.map.annotate.JsonSerialize;  
import com.blog.samples.web.utils.DateSerializer;  

/**  
 * The Class Fund.  
 */  
public class Fund{  

  private String fundId;  
  private String fundDescription;  
  private double bidPrice;  
  private double offerPrice;  
  private Date lastUpdated;  

  public Fund()  
  { }  

  /**  
   * Gets the fund id.  
   *  
   * @return the fund id  
   */  
  public String getFundId() {  
    return fundId;  
  }  

  /**  
   * Sets the fund id.  
   *  
   * @param fundId the new fund id  
   */  
  public void setFundId(String fundId) {  
    this.fundId = fundId;  
  }  

  /**  
   * Gets the fund description.  
   *  
   * @return the fund description  
   */  
  public Object getFundDescription() {  
    return fundDescription;  
  }  

  /**  
   * Sets the fund description.  
   *  
   * @param fundDescription the new fund description  
   */  
  public void setFundDescription(String fundDescription) {  
    this.fundDescription = fundDescription;  
  }  

  /**  
   * Gets the bid price.  
   *  
   * @return the bid price  
   */  
  public double getBidPrice() {  
    return bidPrice;  
  }  

  /**  
   * Sets the bid price.  
   *  
   * @param bidPrice the new bid price  
   */  
  public void setBidPrice(double bidPrice) {  
    this.bidPrice = bidPrice;  
  }  

  /**  
   * Gets the offer price.  
   *  
   * @return the offer price  
   */  
  public double getOfferPrice() {  
    return offerPrice;  
  }  

  /**  
   * Sets the offer price.  
   *  
   * @param offerPrice the new offer price  
   */  
  public void setOfferPrice(double offerPrice) {  
    this.offerPrice = offerPrice;  
  }  

  /**  
   * Gets the last updated.  
   *  
   * @return the last updated  
   */  
  @JsonSerialize(using=DateSerializer.class)  
  public Date getLastUpdated() {  
    return lastUpdated;  
  }  

  /**  
   * Sets the last updated.  
   *  
   * @param lastUpdated the new last updated  
   */  
  public void setLastUpdated(Date lastUpdated) {  
    this.lastUpdated = lastUpdated;  
  }  

  @Override  
  public String toString() {  
    return "Fund [fundId=" + fundId + ", fundDescription="  
        + fundDescription + ", bidPrice=" + bidPrice + ", offerPrice="  
        + offerPrice + ", lastUpdated=" + lastUpdated + "]";  
  }  
}  

This is a very simple class and the only part worth mentioning is the @JsonSerialize(using=DateSerializer.class) annotation on the getLastUpdated method. This annotation ensures that Java dates are converted into a suitable JSON date format before being returned to the client. The DateDeserializer class referenced in the annotation handles this conversion and is defined as follows.

package com.blog.samples.web.utils;  

import java.io.IOException;  
import java.text.SimpleDateFormat;  
import java.util.Date;  
import org.codehaus.jackson.JsonGenerator;  
import org.codehaus.jackson.JsonProcessingException;  
import org.codehaus.jackson.map.JsonSerializer;  
import org.codehaus.jackson.map.SerializerProvider;  

/**  
 * The Class DateSerializer.  
 */  
public class DateSerializer extends JsonSerializer<Date> {  

  /* (non-Javadoc)  
   * @see org.codehaus.jackson.map.JsonSerializer#serialize(java.lang.Object, org.codehaus.jackson.JsonGenerator, org.codehaus.jackson.map.SerializerProvider) 
   */  
  @Override  
  public void serialize(Date value_p, JsonGenerator gen, SerializerProvider prov_p)  
      throws IOException, JsonProcessingException  
  {  
    SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss");  
    String formattedDate = formatter.format(value_p);  
    gen.writeString(formattedDate);  
  }  
}  

Defining REST Operations

Next we’ll create a controller and define the RESTful methods that we want to expose to client applications. Following a standard REST approach we’ll define methods to handle the following different types of request.