Using XML in @RequestBody in Spring REST

1. Overview

While JSON is a de-facto standard for RESTful services, in some cases, we might want to work with XML. We can fall back to XML for different reasons: legacy applications, using a more verbose format, standardized schemas, etc.

Spring provides us with a simple way to support XML endpoints with no work from our side. In this tutorial, we’ll learn how to leverage Jackson XML to approach this problem.

2. Dependencies

The first step is to add the dependency to allow XML mapping. Even if we’re using spring-boot-starter-web, it doesn’t contain the libraries for XML support by default:

<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-xml</artifactId>
    <version>2.16.0</version>
</dependency>

We can leverage the Spring Boot version management system by omitting the version, ensuring the correct Jackson library versions are used across all dependencies.

Alternatively, we can use JAXB to do the same thing, but overall, it’s more verbose, and Jackson generally provides us with a nicer API. However, if we’re using Java 8, JAXB libraries are located in the javax package with the implementation, and we won’t need to add any other dependencies to our application.

On Java versions starting from 9, the javax package was moved and renamed to jakarta, so JAXB requires an additional dependency:

<dependency>
    <groupId>jakarta.xml.bind</groupId>
    <artifactId>jakarta.xml.bind-api</artifactId>
    <version>4.0.0</version>
</dependency>

Also, it needs a runtime implementation for XML mappers, which might create too much confusion and subtle issues.

3. Endpoints

Since JSON is a default format for Spring REST controllers, we need to explicitly identify the endpoints that consume and produce XML. Let’s consider this simple echo controller:

@RestController
@RequestMapping("/users")
public class UserEchoController {
    @ResponseStatus(HttpStatus.CREATED)
    @PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
    public User echoJsonUser(@RequestBody User user) {
        return user;
    }

    @ResponseStatus(HttpStatus.CREATED)
    @PostMapping(consumes = MediaType.APPLICATION_XML_VALUE, produces = MediaType.APPLICATION_XML_VALUE)
    public User echoXmlUser(@RequestBody User user) {
        return user;
    }
}

The only purpose of the controller is to receive a User and send it back. The only difference between these endpoints is that the first works with JSON format. We specify it explicitly in @PostMapping, but for JSON, we can omit the consumes and produces attributes.

The second endpoint works with XML. We must identify it explicitly by providing the correct types to the consumes and produces values. This is the only thing we need to do to configure the endpoint.

4. Mappings

We’ll be working with the following User class:

public class User {
    private Long id;
    private String firstName;
    private String secondName;

    public User() {
    }

    // getters, setters, equals, hashCode
}

Technically, we don’t need anything else, and the endpoint should support the following XML straight away:

<User>
    <id>1</id>
    <firstName>John</firstName>
    <secondName>Doe</secondName>
</User>

However, if we want to provide other names or translate legacy conventions to ones we use in our application, we might want to use special annotations. @JacksonXmlRootElement and @JacksonXmlProperty are the most common annotations to use for this.

If we opt to use JAXB, it is also possible to configure our mappings with annotations only, and there’s a different set of annotations, for example, @XmlRootElement and @XmlAttribute. In general, the process is quite similar. However, note that JAXB might require explicit mapping.

5. Conclusion

Spring REST provides us with a convenient way to create RESTful services. However, they aren’t constrained to JSON only. We can use them with other formats, for example, XML. Overall, the transition is transparent, and the entire setup is made with several strategically placed annotations.