Spring Boot @RestController

Spring Boot @RestController tutorial shows how to use the @RestController annotation in a Spring application to build a Restful controller.

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.

Spring MVC

Spring MVC is the primary web framework built on the Servlet API. It is build on the popular MVC design pattern. MVC (Model-View-Controller) is a software architecture pattern, which separates application into three areas: model, view, and controller. The model represents a Java object carrying data. The view represents the visualization of the data that the model contains. The controller controls the data flow into model object and updates the view when the data changes. It separates the view and model.

Spring Framework 5.0 introduced a parallel reactive stack web framework called Spring WebFlux.


@RestController is a convenience annotation for creating Restful controllers. It is a specialization of @Component and is autodetected through classpath scanning. It adds the @Controller and @ResponseBody annotations. It converts the response to JSON or XML. It does not work with the view technology, so the methods cannot return ModelAndView. It is typically used in combination with annotated handler methods based on the @RequestMapping annotation.

The @Controller annotation is used with the view technology.

Restful application

A RESTFul application follows the REST architectural style, which is used for designing networked applications. RESTful applications generate HTTP requests performing CRUD (Create/Read/Update/Delete) operations on resources. RESTFul applications typically return data in JSON or XML format.

Spring Boot @RestController example

In the following application, we demonstrate the usage of @RestController. The application returns a list of cities as JSON data.

$ tree
├── pom.xml
└── src
    ├── main
    │   ├── java
    │   │   └── com
    │   │       └── zetcode
    │   │           ├── Application.java
    │   │           ├── bean
    │   │           │   └── City.java
    │   │           ├── controller
    │   │           │   └── MyController.java
    │   │           └── service
    │   │               ├── CityService.java
    │   │               └── ICityService.java
    │   └── resources
    │       └── static
    │           └── index.html
    └── test
        └── java

This is the project structure.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" 



This is the Maven pom.xml file. The spring-boot-starter-parent is a parent POM providing dependency and plugin management for applications built with Maven. The spring-boot-starter-web is a starter for building web, including RESTful, applications using Spring MVC. It uses Tomcat as the default embedded container. The spring-boot-maven-plugin packages Spring applications into executable JAR or WAR archives.

package com.zetcode.bean;

public class City {

    private Long id;
    private String name;
    private int population;

    public City() {

    public City(Long id, String name, int population) {
        this.id = id;
        this.name = name;
        this.population = population;

    public Long getId() {
        return id;

    public void setId(Long id) {
        this.id = id;

    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;

    public String toString() {
        return "City{" + "id=" + id + ", name=" + name + 
                ", population=" + population + '}';

This is a City bean. It has id, name, and population attributes.

package com.zetcode.controller;

import com.zetcode.bean.City;
import com.zetcode.service.ICityService;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

public class MyController {
    ICityService cityService;
    @RequestMapping(value = "/getCities")
    public List<City> getCities() {

        List<City> cities = cityService.findAll();
        return cities;

This is MyController. It returns a list of cities in JSON format.

public class MyController {

MyController is annotated with the @RestController annotation.

ICityService cityService;

We inject the CityService with the @Autowired annotation.

@RequestMapping(value = "/getCities")
public List<City> getCities() {

The getCities() method is mapped to the getCities URL pattern; it returns a list of cities, which is converted to JSON by a message converter.

package com.zetcode.service;

import com.zetcode.bean.City;
import java.util.List;

public interface ICityService {

    public List<City> findAll();

The ICityService contains the findAll() contract method.

package com.zetcode.service;

import com.zetcode.bean.City;
import java.util.ArrayList;
import java.util.List;
import org.springframework.stereotype.Service;

public class CityService implements ICityService {

    public List<City> findAll() {

        List<City> cities = new ArrayList<>();
        cities.add(new City(1L, "Bratislava", 432000));
        cities.add(new City(2L, "Budapest", 1759000));
        cities.add(new City(3L, "Prague", 1280000));
        cities.add(new City(4L, "Warsaw", 1748000));
        cities.add(new City(5L, "Los Angeles", 3971000));
        cities.add(new City(6L, "New York", 8550000));
        cities.add(new City(7L, "Edinburgh", 464000));
        cities.add(new City(8L, "Berlin", 3671000));
        return cities;

The CityService contains the implementation of the findAll() method.

<!DOCTYPE html>
        <title>Home page</title>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
            <a href="getCities">Get cities</a>

This is the home page. It contains a link to get all cities.

package com.zetcode;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.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. The @SpringBootApplication annotation enables auto-configuration and component scanning. During the scanning process, the @RestController annotation is looked up and a Spring bean is created from the MyController class.

In this tutorial, we have shown how to use @RestController annotation in a Spring application. You might also be interested in the related tutorials: Java Servlets tutorial, Spring Boot @Controller tutorial, Spring Boot @ExceptionHandler tutorial, Spring Boot upload file, Spring Boot @PathVariable tutorial, Spring Boot @RequestParam tutorial, Spring Boot @ResponseBody tutorial, Java tutorial.