Spring MVC Content Negotiation

1. Overview

This article describes how to implement content negotiation in a Spring MVC project.

Generally, there are three options to determine the media type of a request:

• (Deprecated) Using URL suffixes (extensions) in the request (eg .xml/.json)
• Using URL parameter in the request (eg ?format=json)
• Using Accept header in the request

By default, this is the order in which the Spring content negotiation manager will try to use these three strategies. And if none of these are enabled, we can specify a fallback to a default content type.

2. Content Negotiation Strategies

Let’s start with the necessary dependencies – we are working with JSON and XML representations, so for this article, we’ll use Jackson for JSON:

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>2.10.2</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.10.2</version>
</dependency>

For XML support, we can use either JAXB, XStream, or the newer Jackson-XML support.

Since we have explained the use of the Accept header in an earlier article on HttpMessageConverters, let’s focus on the first two strategies in depth.

3. The URL Suffix Strategy

With the Spring Boot 2.6.x version, the default strategy for matching request paths against registered Spring MVC handler mappings has changed from AntPathMatcher to PathPatternParser.

And as suffix pattern matching is not supported by PathPatternParser, we first need to use the legacy path matcher before making the use of this strategy.

We can add spring.mvc.pathmatch.matching-strategy in application.properties file to switch the default back to AntPathMatcher.

By default, this strategy is disabled, we need to enable this by setting spring.mvc.pathmatch.use-suffix-pattern to true in application.properties:

spring.mvc.pathmatch.use-suffix-pattern=true
spring.mvc.pathmatch.matching-strategy=ant-path-matcher

Once enabled, the framework can check for a path extension right from the URL to determine the output content type.

Before going into configurations, let’s have a quick look at an example. We have the following simple API method implementation in a typical Spring controller:

@RequestMapping(
  value = "/employee/{id}", 
  produces = { "application/json", "application/xml" }, 
  method = RequestMethod.GET)
public @ResponseBody Employee getEmployeeById(@PathVariable long id) {
    return employeeMap.get(id);
}

Let’s invoke it by making use of the JSON extension to specify the media type of the resource:

curl http://localhost:8080/spring-mvc-basics/employee/10.json

Here’s what we might get back if we use a JSON extension:

{
    "id": 10,
    "name": "Test Employee",
    "contactNumber": "999-999-9999"
}

And here’s what the request-response will look like with XML:

curl http://localhost:8080/spring-mvc-basics/employee/10.xml

The response body:

<employee>
    <contactNumber>999-999-9999</contactNumber>
    <id>10</id>
    <name>Test Employee</name>
</employee>

Now, if we do not use any extension or use one that is not configured, the default content type will be returned:

curl http://localhost:8080/spring-mvc-basics/employee/10

Let’s now have a look at setting up this strategy – with both Java and XML configurations.

3.1. Java Configuration

public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
    configurer.favorPathExtension(true).
    favorParameter(false).
    ignoreAcceptHeader(true).
    useJaf(false).
    defaultContentType(MediaType.APPLICATION_JSON); 
}

Let’s go over the details.

First, we’re enabling the path extensions strategy. It’s also worth mentioning that as of Spring Framework 5.2.4, the favorPathExtension(boolean) method is deprecated in order to discourage the use of path extensions for content negotiations.

Then, we’re disabling the URL parameter strategy as well as the Accept header strategy – because we want to only rely on the path extension way of determining the type of the content.

We’re then turning off the Java Activation Framework; JAF can be used as a fallback mechanism to select the output format if the incoming request doesn’t match any of the strategies we configured. We’re disabling it because we’re going to configure JSON as the default content type. Please note that the useJaf() method is deprecated as of Spring Framework 5.

And finally – we are setting up JSON to be the default. That means if none of the two strategies are matched, all incoming requests will be mapped to a controller method that serves JSON.

3.2. XML Configuration

Let’s also have a quick look at the same exact configuration, only using XML:

<bean id="contentNegotiationManager" 
  class="org.springframework.web.accept.ContentNegotiationManagerFactoryBean">
    <property name="favorPathExtension" value="true" />
    <property name="favorParameter" value="false"/>
    <property name="ignoreAcceptHeader" value="true" />
    <property name="defaultContentType" value="application/json" />
    <property name="useJaf" value="false" />
</bean>

4. The URL Parameter Strategy

We’ve used path extensions in the previous section – let’s now set up Spring MVC to make use of a path parameter.

We can enable this strategy by setting the value of the favorParameter property to true.

Let’s have a quick look at how that would work with our previous example:

curl http://localhost:8080/spring-mvc-basics/employee/10?mediaType=json

And here’s what the JSON response body will be:

{
    "id": 10,
    "name": "Test Employee",
    "contactNumber": "999-999-9999"
}

If we use the XML parameter, the output will be in XML form:

curl http://localhost:8080/spring-mvc-basics/employee/10?mediaType=xml

The response body:

<employee>
    <contactNumber>999-999-9999</contactNumber>
    <id>10</id>
    <name>Test Employee</name>
</employee>

Now let’s do the configuration – again, first using Java and then XML.

4.1. Java Configuration

public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
    configurer.favorPathExtension(false).
    favorParameter(true).
    parameterName("mediaType").
    ignoreAcceptHeader(true).
    useJaf(false).
    defaultContentType(MediaType.APPLICATION_JSON).
    mediaType("xml", MediaType.APPLICATION_XML). 
    mediaType("json", MediaType.APPLICATION_JSON); 
}

Let’s read through this configuration.

First, of course, the path extension and the Accept header strategies are disabled (as well as JAF).

The rest of the configuration is the same.

4.2. XML Configuration

<bean id="contentNegotiationManager" 
  class="org.springframework.web.accept.ContentNegotiationManagerFactoryBean">
    <property name="favorPathExtension" value="false" />
    <property name="favorParameter" value="true"/>
    <property name="parameterName" value="mediaType"/>
    <property name="ignoreAcceptHeader" value="true" />
    <property name="defaultContentType" value="application/json" />
    <property name="useJaf" value="false" />

    <property name="mediaTypes">
        <map>
            <entry key="json" value="application/json" />
            <entry key="xml" value="application/xml" />
        </map>
    </property>
</bean>

Also, we can have both strategies (extension and parameter) enabled at the same time:

public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
    configurer.favorPathExtension(true).
    favorParameter(true).
    parameterName("mediaType").
    ignoreAcceptHeader(true).
    useJaf(false).
    defaultContentType(MediaType.APPLICATION_JSON).
    mediaType("xml", MediaType.APPLICATION_XML). 
    mediaType("json", MediaType.APPLICATION_JSON); 
}

In this case, Spring will look for path extension first, if that is not present then will look for path parameter. And if both of these are not available in the input request, then the default content type will be returned back.

5. The Accept Header Strategy

If the Accept header is enabled, Spring MVC will look for its value in the incoming request to determine the representation type.

We have to set the value of ignoreAcceptHeader to false to enable this approach and we’re disabling the other two strategies just so that we know we’re only relying on the Accept header.

5.1. Java Configuration

public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
    configurer.favorPathExtension(true).
    favorParameter(false).
    parameterName("mediaType").
    ignoreAcceptHeader(false).
    useJaf(false).
    defaultContentType(MediaType.APPLICATION_JSON).
    mediaType("xml", MediaType.APPLICATION_XML). 
    mediaType("json", MediaType.APPLICATION_JSON); 
}

5.2. XML Configuration

<bean id="contentNegotiationManager" 
  class="org.springframework.web.accept.ContentNegotiationManagerFactoryBean">
    <property name="favorPathExtension" value="true" />
    <property name="favorParameter" value="false"/>
    <property name="parameterName" value="mediaType"/>
    <property name="ignoreAcceptHeader" value="false" />
    <property name="defaultContentType" value="application/json" />
    <property name="useJaf" value="false" />

    <property name="mediaTypes">
        <map>
            <entry key="json" value="application/json" />
            <entry key="xml" value="application/xml" />
        </map>
    </property>
</bean>

Finally, we need to switch on the content negotiation manager by plug-in it into the overall configuration:

<mvc:annotation-driven content-negotiation-manager="contentNegotiationManager" />

6. Conclusion

And we’re done. We looked at how content negotiation works in Spring MVC and we focused on a few examples of setting that up to use various strategies to determine the content type.

The full implementation of this article can be found over on GitHub.