Content Negotiation in Spring Boot

Introduction

Welcome to this lesson on Content Negotiation in Spring Boot! In the previous lessons, we focused on validating request data and handling exceptions, essential skills for building robust RESTful APIs. Today, we'll delve into content negotiation—a vital aspect that allows your API to serve responses in different formats, like JSON and XML, based on the client's request.

Understanding Content Negotiation

Content negotiation is crucial when you want a single endpoint to serve results in various formats. This is particularly useful when different clients use your public endpoint and prefer different response formats. For example, mobile applications may request JSON, while legacy systems might require XML. In this lesson, we'll cover content negotiation for XML and JSON formats in Spring Boot. Other formats like YAML, plain text, and PDF can also be supported by adding the appropriate dependencies and configurations. Here is an example of a TodoItem object returned in JSON format: JSON {"id": 1, "title": "Read book", "description": "Read the first chapter of 'Effective Java'"} And here is the same TodoItem object returned in XML format: XML <TodoItem> <id>1</id> <title>Read book</title> <description>Read the first chapter of 'Effective Java'</description> </TodoItem>

Adding Necessary Dependencies

First, let's add the necessary dependencies to our build.gradle script: Groovy implementation 'com.fasterxml.jackson.dataformat:jackson-dataformat-xml' implementation 'jakarta.xml.bind:jakarta.xml.bind-api:3.0.1' jackson-dataformat-xml : This dependency includes the necessary components for serializing and deserializing XML data using Jackson. jakarta.xml.bind-api : This dependency provides the Jakarta XML Binding API, which is used for converting Java objects to XML and vice versa.

Changes on the Controller

To enable content negotiation, you can use the produces attribute in your mapping annotations to specify the supported media types. Spring Boot will automatically handle the content negotiation based on your configuration. Here's a code snippet for our TodoItemController: Java@GetMapping(value = "/{id}", produces = { MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE }) public TodoItem getTodoItemById(@PathVariable int id) { return todoItemRepository.findById(id).orElseThrow(() -> new NoSuchElementException("Todo item with id " + id + " not found")); } The produces attribute tells Spring Boot which media types this endpoint can return. Based on the content negotiation strategy you configure, Spring will determine the appropriate response format and automatically serialize your TodoItem object to either JSON or XML.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Spring Boot offers two primary strategies for content negotiation:

URL Parameter Strategy: GET /todo/123?format=xml to request XML data or GET /todo/123?format=json to request JSON data.
Accept Header Strategy: GET /todo/123 with Accept: application/xml in the request header to request XML data or GET /todo/123 with Accept: application/json in the request header to request JSON data.

The URL Parameter Strategy

In the URL Parameter Strategy, the response format is determined by a parameter in the URL query string. For example, the URL GET /todos?format=xml would request XML data.

Here's a configuration snippet using this strategy:

Java

package com.codesignal;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ContentNegotiationConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class ContentNegotiationConfig implements WebMvcConfigurer {

    @Override
    public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
        configurer
            .favorParameter(true) // Enable content negotiation via URL parameter
            .parameterName("format") // Specify the parameter name to look for in the URL
            .defaultContentType(MediaType.APPLICATION_JSON) // Set the default content type
            .mediaType("json", MediaType.APPLICATION_JSON) // Map "json" to MediaType.APPLICATION_JSON
            .mediaType("xml", MediaType.APPLICATION_XML); // Map "xml" to MediaType.APPLICATION_XML
    }
}

package com.codesignal;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ContentNegotiationConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class ContentNegotiationConfig implements WebMvcConfigurer {

    @Override
    public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
        configurer
            .favorParameter(true) // Enable content negotiation via URL parameter
            .parameterName("format") // Specify the parameter name to look for in the URL
            .defaultContentType(MediaType.APPLICATION_JSON) // Set the default content type
            .mediaType("json", MediaType.APPLICATION_JSON) // Map "json" to MediaType.APPLICATION_JSON
            .mediaType("xml", MediaType.APPLICATION_XML); // Map "xml" to MediaType.APPLICATION_XML
    }
}

Explanation:

favorParameter(true): This method enables content negotiation via a URL parameter. When set to true, Spring will use the specified query parameter to determine the response format.
parameterName("format"): This method sets the name of the URL parameter to be used for content negotiation. In this case, the format parameter will be used.
defaultContentType(MediaType.APPLICATION_JSON): This sets the default content type to JSON in case the URL parameter is not specified.
mediaType("json", MediaType.APPLICATION_JSON) and mediaType("xml", MediaType.APPLICATION_XML): These methods map the string values json and xml to their respective media types.

The Accept Header Strategy

In the Accept Header Strategy, the client specifies the desired response format using the HTTP Accept header. For example, setting Accept: application/xml in the request header informs the server to respond with XML data.

Here's the configuration snippet for this strategy: