Quicknotes on RESTful Spring

To implement a “RESTful” solution is so easy with Spring 3 MVC annotation (a.k.a. @MVC), it makes me think that maybe we can extend the solution to a “RESTful Web Services” solution.

In this post, I would like share some simple steps for implementing a RESTful solution with Spring 3 @MVC. Then, I will provide a few very short paragraphs on my findings and thoughts on Spring RESTful web services.

Steps for implementing a RESTful solution with Spring 3 @MVC

Step 1. Create a Spring MVC Web App

If you don’t know how to create a Spring MVC web application, you can take a look at the “Developing a Spring Framework MVC application step-by-step” documents provided on the official Spring web site. If you feel the document is a bit too long or too detailed, which I do feel so, please Google on the web to find out some other simple tutorials or examples. By the way, you might like to check out the “Spring by Example” web site as a starting point.

Step 2. Support All 4 REST Methods

If the client of your RESTful solution is a browser, not a costumed web client, then please beware that HTML only supports “GET” and “POST” methods, i.e. browsers might not know how to handle HTML form, whose action method is “PUT” or “DELETE”. To get around this, you can add a hidden filed in your web form to pass the “real” method type back to your web application. That is how Spring does it. They add a hidden “_method” parameter. And to make our life easier, Spring provides the HiddenHttpMethodFilter, which interprets and converts the hidden paramter into the corresponding HTTP method request. To do so, simply add this filter to your web.xml and map it to your Spring servlet.

For example,

    <servlet>
        <servlet-name>your-spring-servlet</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    </servlet>

	<filter>
		<filter-name>hiddenHttpMethodFilter</filter-name>
		<filter-class>org.springframework.web.filter.HiddenHttpMethodFilter</filter-class>
	</filter>

	<filter-mapping>
		<filter-name>hiddenHttpMethodFilter</filter-name>
		<servlet-name>your-spring-servlet</servlet-name>
	</filter-mapping>

Step 3. Use Annotation in Controller

If you don’t know how use annotation with Spring controller, I would recommend reading the post on “Annotated Web MVC Controllers in Spring 2.5″ as a starting point.

Basically, add the line “@Controller” above your class declaration, and add the line “@RequestMapping(value=”/someUrl”, method=RequestMethod.GET)” above your method declaration.

For example,

@Controller
public class myController {

   @RequestMapping(value="/someUrl", method=RequestMethod.GET)
   public someMethod( someInputParameters ) {   }
}

Step 4. Some Enhancements

• @RequestMapping : The Spring Request Mapping annotation can help you parse the URL and convert them as input parameters to your method. To find out more, please check out the post on “REST in Spring 3: @MVC”
• Spring MVC annotation : The article “Spring 2.5: New Features in Spring MVC” provides a nice introduction on various features of Spring MVC annotation.
• URL Mapping : If you want to use the “url-pattern” defined in the web.xml file to control what URL will be routed to your special REST controller, please beware of the constraints of url-pattern. For example, url pattern of “/rest/*” does not cover url like “/rest/something/somevalue”. To get around this issue, you might want to consider the url pattern of “*.rest”, or use some tool like “Url Rewrite Filter”.
• Content Negotiation : If you want your web app to return different representations of the same resource based on the “Accept” HTTP header sent from client (a.k.a. content negotiation), you can use the Spring ContentNegotiatingViewResolver. To find out more, you can check out the article on “Content Negotiation using Spring MVC’s ContentNegotiatingViewResolver” as a starting point.
• Output Format : If you want your web app to return different representations of the same resource based on some input provided by the client (e.g. if the url is /*/rss/*, then return in RSS format), you can do so with the different views provided by Spring. The two views worth mentioning are AbstractRssFeedView and MarshallingView.

About RESTful Web Services and Spring

First of all, please notice that RESTful Web Services are not SOAP-based web services, there is no “official” standard for RESTful web service. REST is an architecture, not a protocol. Of course, you can try to use the MarshallingView to format the output to make it look like SOAP-based web service.

Besides that, Spring does NOT adopt or integrate with JAX-RS. Arjen Poutsma has made some good arguments and posted it as one of the comments on the article “Getting REST Right in Spring 3.0″.

* JAX-RS annotations overlap with the Spring MVC annotations introduced in 2.5.
* JAX-RS is semantically different than Spring MVC, i.e. request-scoped by default vs. singleton by default
* JAX-RS focusses on RESTful web services, while historically Spring MVC had a focus on web sites (though that changed in 3.0)

Also, to me, RESTful Spring @MVC is RESTful Web Services, as it satisfies the principles of REST web service design

Last but not the least, thank you for reading this post. And please feel free to provide your feedback.

Thanks.