Combining JSON and XML in RESTful web services with Spring MVC

There are occasions when you need to support multiple representations of the same resource in a REST API. For example, a smartphone client might want the resource to be represented in JSON while your B2B partner's application that is integrating through your API wants the representation to be XML.

Willie Wheeler wrote an excellent blog post about how to support both XML and JSON from a web service endpoint using the new features of the @RequestMapping annotation in Spring 3.1. The example in the blog post, by intention, uses two different URLs for the two different representations.

However, when dealing with RESTful services the preferred approach to design your API would usually be to have a single URL for the resource regardless of what representation the requesting client is asking for. A way to solve this is to let the requesting client specify what representation it prefers via the Accept header in the HTTP request. The server will examine the request header and send back the resource in the proper representation. This can very easily be implemented by using Spring MVC and I figured I will show you how this can be accomplished with the following example.

In our example we have a web service that you can use to get information about a user. At first, let say we only support JSON. (You can get the complete source for the example at github)

A user in the service is represented by the user entity:

public class User {

 private Long id;
 private String name;

 public User() {
 }

 public User(Long id, String name) {
  this.id = id;
  this.name = name;
 }

 public Long getId() {
  return id;
 }

 public void setId(Long id) {
  this.id = id;
 }

 public String getName() {
  return name;
 }

 public void setName(String name) {
  this.name = name;
 }

}

The controller that serves the requests looks like the following:

@Controller
public class RESTController {
 
 @RequestMapping("/users/{id}")
 @ResponseBody
 public User getUser(@PathVariable Long id) {
  return new User(id, "John Doe");
 }
 
}

and the Spring configuration needed to get this to work is this:

<mvc:annotation-driven />
<context:component-scan base-package="se.sawano.spring.examples" />

And that's it! No more configuration is needed. The reason for why this works is because the message converter MappingJacksonHttpMessageConverter is added automatically by Spring if it is present on the classpath.

With the above setup, the web service will always return the data in JSON. Regardless if the Accept header in the request is asking for XML. If we want to extend our web service to also be able to return the data formatted in XML all we need to do is annotate our User POJO with the @XmlRootElement annotation. The User POJO will now look like:

import javax.xml.bind.annotation.XmlRootElement;


@XmlRootElement
public class User {
 
 private Long id;
 private String name;
 ...

Now, if you make a request with the Accept header application/json the response will be in JSON format just as before. But if you make a request with an application/xml Accept header the response will be in XML. The message converter used for the XML representation in this case is the Jaxb2RootElementHttpMessageConverter, and like the JSON message converter it is added if present on the classpath. You will also get the XML response for the accept headers text/xml and application/*+xml because the Jaxb2RootElementHttpMessageConverter supports those media types by default.

Running the code

There are three integrations tests included in the source code (in RESTControllerTestIT.java) that you can use to see how it all works. To see it in action use:

:> mvn verify

This will launch a Jetty instance, deploy the webapp, run the tests and then shut down the Jetty. Or if you prefer to run the tests individually start and deploy with:

:> mvn jetty:run

and then run the tests as ordinary JUnit tests.
Now go ahead and browse the source code or get it as a zip.


I hope this post have helped to show you how simple it is to get support for both JSON and XML in web services using Spring MVC.