Spring @Controller Vs. @RestController: What’s Difference?

Learn the main differences between @Controller and @RestController annotations in Spring framework and how the API response handling differs for each annotation.

At a high level, @RestController is a convenient annotation that combines @Controller and @ResponseBody annotations, thus eliminating the need to apply @ResponseBody annotation separately to each handler method.

@RestController = @Controller + @ResponseBody

1. The @Controller Annotation

In Spring, incoming requests are handled by a handler method inside a @Controller annotated class. Usually, the dispatcher servlet is responsible for identifying the controller and appropriate request handler method inside the controller by URL matching.

1.1. When to Use?

The @Controller is one of the stereotype annotations and specialization of @Component, allowing for annotated classes to be auto-detected through classpath scanning.

@Component
public @interface Controller {
}

In Spring MVC, the @Controller annotation is typically used in UI-based applications where the response is generally an HTML page. The handler method returns the response “view name” which is resolved to a view technology file (e.g. JSP or FTL) by view resolver. And then, the parsed view content is sent back to the browser.

@Controller
@RequestMapping("users")
public class UserController {

    @GetMapping("/")
    public String displayUserInfo(@PathVariable Long id) {
        ...
    }
}

1.2. Using @Controller With @ResponseBody

Imagine if the request is sent from AJAX technology and the client is looking for a response in JSON format (such as a REST API) to parse the result in the browser and display it as needed. Here, we must use @ResponseBody annotation along with @Controller.

In the following code, the getUserById() method will be invoked if we send an HTTP GET request to URL: /users/1.

@Controller
@RequestMapping("users")
public class UserController {

    @GetMapping("{id}", produces = "application/json")
    public @ResponseBody User getUserById(@PathVariable Long id) {
        ...
    }
}

The @ResponseBody annotation indicates a method return value should be bound to the web response body i.e. no view resolver is needed.

2. The @RestController Annotation

As the name suggests, @RestController is used in the case of REST style controllers i.e. handler methods shall return the JSON/XML response directly to the client rather than using view resolvers. The @RestController is a convenience annotation that combines the @Controller and @ResponseBody annotations.

...
@Controller
@ResponseBody
public @interface RestController {
	//...
}

2.1. When to Use?

The @RestController annotation is specifically designed for building RESTful web services or APIs. Using @RestController eliminates the need to annotate each handler method with @ResponseBody annotation.

Such APIs can return data directly in the response body, typically in JSON or XML format.

2.2. How to Use?

For example, we can rewrite the UserController as follows. Notice that we have removed the explicit @ResponseBody annotation.

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

    @GetMapping("{id}", produces = "application/json")
    public User getUserById(@PathVariable Long id) {
        ...
    }
}

3. Conclusion

Clearly, from the above discussion, @RestController is a convenience annotation that does nothing more than add the @Controller and @ResponseBody annotations in a single statement.

• Use @Controller when building traditional web applications that render views.
• Use @RestController when building RESTful APIs that require data (typically JSON or XML) to be directly returned in the response body.
• If you want a method in a @Controller to return raw data or JSON, you can use @ResponseBody on that method.

Happy Learning !!