Spring Boot ResponseEntity

last modified May 22, 2022

Spring Boot ResponseEntity tutorial shows how to use ResponseEntity in a Spring application.

Spring is a popular Java application framework and Spring Boot is an evolution of Spring that helps create stand-alone, production-grade Spring based applications easily.

ResponseEntity

ResponseEntity represents an HTTP response, including headers, body, and status. While @ResponseBody puts the return value into the body of the response, ResponseEntity also allows us to add headers and status code.

Groovy examples

We show some controller methods utilizing ResponseEntity classes to create responses.

package com.zetcode

@RestController
class MyApp {

    @GetMapping("/status")
    ResponseEntity<String> home() {
        ResponseEntity.status(HttpStatus.OK).body("OK")
    }

    @GetMapping("/notfound")
    ResponseEntity<String> notfound() {
        ResponseEntity.notFound().build()
    }

    @GetMapping("/badrequest")
    ResponseEntity<String> badRequest() {
        ResponseEntity.badRequest().body("Bad request")
    }
}

The example shows how to create common status OK, not found, and bad request responses.

$ curl -i localhost:8080/status
HTTP/1.1 200 
Content-Type: text/plain;charset=UTF-8
Content-Length: 2
Date: Sun, 22 May 2022 21:11:20 GMT

$ curl -i localhost:8080/notfound
HTTP/1.1 404 
Content-Length: 0
Date: Sun, 22 May 2022 21:11:51 GMT

$ curl -i localhost:8080/badrequest
HTTP/1.1 400 
Content-Type: text/plain;charset=UTF-8
Content-Length: 11
Date: Sun, 22 May 2022 21:12:15 GMT
Connection: close

---

package com.zetcode

import java.time.LocalDate
import groovy.transform.Immutable

@Immutable
class User {
    String name
    String occupation
 }


@RestController
class MyApp {

    def users = [

        new User('John Doe', 'gardener'),
        new User('Roger Roe', 'driver'),
        new User('Kim Smith', 'teacher'),
        new User('Joe Nigel', 'artist'),
        new User('Liam Strong', 'teacher'),
        new User('Robert Young', 'gardener')
    ]

    @GetMapping("/users")
    ResponseEntity<User> home() {
        ResponseEntity.ok().body(users)
    }

    @GetMapping("/random-user")
    ResponseEntity<User> notfound() {

        def rnd = new Random()
        def ru = users.get(rnd.nextInt(users.size()))
        ResponseEntity.ok().body(ru)
    }
}

In the example, we have two URL paths that send a list of users and a random user utilizing ResponseEntity.

$ curl localhost:8080/random-user
{"name":"Roger Roe","occupation":"driver"}
$ curl localhost:8080/users
[{"name":"John Doe","occupation":"gardener"},
{"name":"Roger Roe","occupation":"driver"},
{"name":"Kim Smith","occupation":"teacher"},
{"name":"Joe Nigel","occupation":"artist"},
{"name":"Liam Strong","occupation":"teacher"},
{"name":"Robert Young","occupation":"gardener"}]

Spring Boot ResponseEntity example

In the following application, we demonstrate the usage of ResponseEntity. The application has two methods: one method uses ResponseEntity to create an HTTP response, the other one @ResponseBody.

build.gradle
...
src
├── main
│   ├── java
│   │   └── com
│   │       └── zetcode
│   │           ├── Application.java
│   │           ├── controller
│   │           │   └── MyController.java
│   │           └── model
│   │               └── Country.java
│   └── resources
│       └── static
│           └── index.html
└── test
    ├── java
    └── resources

This is the project structure of the Spring application.

plugins {
    id 'org.springframework.boot' version '2.6.7'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    id 'java'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

This is the Gradle build file. The spring-boot-starter-web is a dependency for creating Spring Boot web applications using Spring MVC.

package com.zetcode.model;

import java.util.Objects;

public class Country {

    private String name;
    private int population;

    public String getName() {
        return name;
    }

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

    public int getPopulation() {
        return population;
    }

    public void setPopulation(int population) {
        this.population = population;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        Country country = (Country) o;
        return population == country.population && Objects.equals(name, country.name);
    }

    @Override
    public int hashCode() {
        return Objects.hash(name, population);
    }

    @Override
    public String toString() {
        final StringBuilder sb = new StringBuilder("Country{");
        sb.append("name='").append(name).append('\'');
        sb.append(", population=").append(population);
        sb.append('}');
        return sb.toString();
    }
}

This is the Country bean. It has two attributes: name and population.

package com.zetcode.controller;

import com.zetcode.model.Country;
import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;

@Controller
public class MyController {

    @RequestMapping(value = "/getCountry")
    public ResponseEntity<Country> getCountry() {

        var c = new Country();
        c.setName("France");
        c.setPopulation(66984000);

        var headers = new HttpHeaders();
        headers.add("Responded", "MyController");

        return ResponseEntity.accepted().headers(headers).body(c);
    }

    @RequestMapping(value = "/getCountry2")
    @ResponseBody
    public Country getCountry2() {

        var c = new Country();
        c.setName("France");
        c.setPopulation(66984000);

        return c;
    }
}

The controller contains two methods. The first one uses ResponseEntity, the second one @ResponseBody.

@RequestMapping(value = "/getCountry")
public ResponseEntity<Country> getCountry() {

The getCountry() method is mapped to the getCountry URL pattern; it returns a ResponseEntity of type Country.

var c = new Country();
c.setName("France");
c.setPopulation(66984000);

We create a Country bean; this bean is returned in the response.

var headers = new HttpHeaders();
headers.add("Responded", "MyController");

We create an instance of HttpHeaders and add a new header value.

return ResponseEntity.accepted().headers(headers).body(c);

A ResponseEntity is returned. We give ResponseEntity a custom status code, headers, and a body.

@RequestMapping(value = "/getCountry2")
@ResponseBody
public Country getCountry2() {

    var c = new Country();
    c.setName("France");
    c.setPopulation(66984000);

    return c;
}

With @ResponseBody, only the body is returned. The headers and status code are provided by Spring.

<!DOCTYPE html>
<html>
    <head>
        <title>Home page</title>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
    </head>
    <body>
        <p>
            <a href="getCountry">Get country 1</a>
        </p>

        <p>
            <a href="getCountry2">Get country 2</a>
        </p>

    </body>
</html>

This is the home page. It contains two links.

package com.zetcode;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Application  {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Application is the entry point which sets up Spring Boot application.

$ curl localhost:8080/getCountry -I
HTTP/1.1 202 
Responded: MyController
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sat, 14 May 2022 10:48:33 GMT

When calling the first method, we can see the chosen 202 status code and the custom header value.

In this tutorial, we have shown how to use ResponseEntity in a Spring Boot application.

List all Spring Boot tutorials.