Spring @Controller and @RestController

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 for writing REST APIs and combines @Controller and @ResponseBody annotations, thus eliminating the need to apply @ResponseBody annotation to each handler method.

@RestController = @Controller + @ResponseBody

1. @Controller

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.

The @Controller is a specialization of @Component, allowing for annotated classes to be auto-detected through classpath scanning.

...
@Component
public @interface Controller {
}

A spring MVC, the @Controller 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) {
        ...
    }
}

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. @RestController

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 {
	//...
}

Using @RestController eliminates the need to annotate each handler method with @ResponseBody annotation. So, we can rewrite the UserController as follows:

@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 adds the @Controller and @ResponseBody annotations in a single statement.

A key difference between a traditional MVC @Controller and the RESTful web service @RestController is the way that the HTTP response body is created. Rather than relying on a view technology to perform server-side rendering of the data to HTML, a rest controller simply populates and returns the domain object itself.

The object data is written directly to the HTTP response as JSON or XML and parsed by the client to further process it for modifying the existing view or for any other purpose.

Happy Learning !!