@RestController

#Introduction

If you're a Java backend developer, this is probably the most frequently used annotation in Spring Boot — every REST API you build starts here. Understanding @RestController means understanding how Spring Boot converts your Java objects into JSON and sends them back to the client.

#What is @RestController?

@RestController is a specialized Spring annotation for creating RESTful web services. Unlike @Controller, it does not return a view (HTML/JSP/Thymeleaf). Instead, it returns data (usually JSON).

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return new User(id, "Rahul");
    }
}

GET /users/1 returns:

{
  "id": 1,
  "name": "Rahul"
}

#Why Was @RestController Introduced?

Before Spring 4, developers wrote:

@Controller
public class UserController {

    @ResponseBody
    @GetMapping("/users")
    public User getUser() {
        return new User(1, "Rahul");
    }
}

Every REST method required @ResponseBody. Spring 4.0 simplified it — now we write @RestController public class UserController {}.

Internal Definition

Conceptually:

@Target(TYPE)
@Retention(RUNTIME)
@Controller
@ResponseBody
public @interface RestController {
}

So every method automatically behaves as if it has @ResponseBody.

#@Controller vs @RestController

Example

@Controller
public class HomeController {

    @GetMapping("/")
    public String home() {
        return "home";   // Spring searches home.html or home.jsp
    }
}

@RestController
public class UserController {

    @GetMapping("/")
    public String home() {
        return "Hello";   // the response body is literally: Hello
    }
}

No ViewResolver involved.

#Request Flow

For GET /users/10:

Spring receives a User; the browser receives JSON. Where did the JSON come from? Jackson.

#Jackson — Serialization and Deserialization

Spring Boot includes Jackson by default (via spring-boot-starter-web).

Jackson performs both automatically.

Complete REST Flow

Client sends POST /users with body {"name": "Rahul"}:

#@ResponseBody

@Controller
public class TestController {

    @ResponseBody
    @GetMapping("/hello")
    public String hello() {
        return "Hello";
    }
}

• Without @ResponseBody, Spring thinks Hello is a view name.
• With @ResponseBody, Spring writes Hello directly into the HTTP response body.

@RestController applies this behaviour to all methods.

#HttpMessageConverter

Interviewers love this topic. The controller returns a User — who converts it into JSON? An HttpMessageConverter.

This converter is automatically registered by Spring Boot.

#Returning Different Types

Professional APIs usually return ResponseEntity:

@GetMapping("/{id}")
public ResponseEntity<User> get(@PathVariable Long id) {
    return ResponseEntity.ok(user);
    // or: return ResponseEntity.notFound().build();
}

This gives complete control over status code, headers and body. (ResponseEntity has its own chapter.)

#Content Negotiation

If the client sends Accept: application/json, Spring returns JSON. If it sends Accept: application/xml and XML converters are configured (e.g. jackson-dataformat-xml), Spring can return XML instead. This is called content negotiation.

#REST APIs Are Stateless

Controllers should not store user-specific data — multiple users share the same controller instance.

// ❌ Wrong
@RestController
public class UserController {

    private User currentUser;
}

// ✅ Correct — use method parameters and local variables
@GetMapping("/{id}")
public User get(@PathVariable Long id) {
}

#Real Enterprise Architecture

#Internal Working

#Key Takeaways

• @RestController = @Controller + @ResponseBody.
• It's designed for REST APIs that return data instead of views.
• DispatcherServlet routes requests.
• HttpMessageConverter and Jackson handle JSON serialization and deserialization.
• REST controllers should remain stateless and delegate business logic to services.
• Returning DTOs is generally preferable to returning JPA entities directly.