August 21, 2018

Micronaut Mastery: Return Response Based On HTTP Accept Header

Suppose we want our controller methods to return a JSON response when the HTTP Accept header is set to application/json and XML when the Accept header is set to application/xml. We can access the values of HTTP headers in our controller methods by adding an argument of type HttpHeaders to our method definition and Micronaut will add all HTTP headers with their values as HttpHeaders object when we run the application. In our method we can check the value of the Accept header and return a different value based on the header value.

In the following example controller we have a sample method with an argument of type HttpHeaders. We check the value of the Accept header using the method accept and return either XML or JSON as response.

package mrhaki.micronaut;

import io.micronaut.http.HttpHeaders;
import io.micronaut.http.HttpResponse;
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;

public class MessageController {
    public HttpResponse<?> sample(final HttpHeaders headers) {
        // Simple object to be returned from this method either
        // as XML or JSON, based on the HTTP Accept header.
        final Message message = new Message("Micronaut is awesome");

        // Check if HTTP Accept header is "application/xml".
        if (headerAcceptXml(headers)) {
            // Encode messages as XML.
            final String xml = encodeAsXml(message);
            // Return response and set content type 
            // to "application/xml".
            return HttpResponse.ok(xml)
        // Default response as JSON.
        return HttpResponse.ok(message);

     * Check HTTP Accept header with value "application/xml"
     * is sent by the client.
     * @param headers Http headers sent by the client.
     * @return True if the Accept header contains "application/xml".
    private boolean headerAcceptXml(final HttpHeaders headers) {
        return headers.accept().contains(MediaType.APPLICATION_XML_TYPE);

     * Very simple way to create XML String with message content.
     * @param message Message to be encoded as XML String.
     * @return XML String with message content.
    private String encodeAsXml(final Message message) {
        return String.format("<content>%s</content>", message.getContent());


The Message class that is converted to XML or JSON is simple:

package mrhaki.micronaut;

public class Message {

    final String content;

    public Message(final String content) {
        this.content = content;

    public String getContent() {
        return content;


When we run the application and GET /message with HTTP Accept header value application/xml we get the following response:

<content>Micronaut is awesome</content>

And with HTTP Accept header value application/json we get the following response:

    "content": "Micronaut is awesome"

We can test our controller with the following Spock specification:

package mrhaki.micronaut

import io.micronaut.context.ApplicationContext
import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpResponse
import io.micronaut.http.HttpStatus
import io.micronaut.http.MediaType
import io.micronaut.http.client.RxHttpClient
import io.micronaut.runtime.server.EmbeddedServer
import spock.lang.AutoCleanup
import spock.lang.Shared
import spock.lang.Specification

class MessageControllerSpec extends Specification {

    private static EmbeddedServer embeddedServer =

    private static RxHttpClient client =
                          .createBean(RxHttpClient, embeddedServer.getURL())

    void "get message as XML"() {
        final request = HttpRequest.GET("/message").accept(MediaType.APPLICATION_XML_TYPE)
        HttpResponse response = client.toBlocking().exchange(request, String)

        response.status == HttpStatus.OK
        response.body() == 'Micronaut is awesome'

    void "get message as JSON"() {
        HttpResponse response = client.toBlocking().exchange("/message", Message)

        response.status == HttpStatus.OK
        response.body().getContent() == 'Micronaut is awesome'

Written with Micronaut 1.0.0.M4.