RestController vs. Controller: What's the difference?
The key difference between the Spring Controller and RestController is that the Controller annotated class invokes a separate, rending phase to format data before a response is sent back to the client, while the RestController annotated class skips this rendering phase and just embeds JSON, text or XML into the body of the HTTP response. Classes decorated with the Spring @RestController stereotype implicitly add a @ResponseBody annotation to every method that handles an HTTP request.
What does a Spring Web Controller do?
Every HTTP request handling method in a Spring Web Controller class performs the following three tasks:
- Inspect the incoming requests, and extract pertinent data.
- Process requests, and interact with necessary back-end systems.
- Populate JavaBeans with the data required to render a response for the client.
If a rich web client makes the request, the Controller calls on a custom renderer to format the JavaBeans' data in a visually appealing manner. Popular templating engines and rendering technologies commonly used with Spring Boot and Spring MVC include the following:
- JSP.
- Thymeleaf.
- FreeMarker.
- Mustache.
Developers use these client-focused technologies to transform the Controller's data into markup, such as HTML, that's easily displayed in a web browser. RESTful clients don't require marked-up data, only that the returned data is in the form of JSON, XML or even plain text. And therein lies the key distinction between Controller and RestController.
RestController vs. traditional Spring MVC
Prior to version 4 of the Spring Framework a decade ago, developers who wanted to skip the rendering step simply added the @ResponseBody annotation to methods. Spring automatically converted the data returned from the Controller's HTTP request handler method into JSON or XML and embedded it in the body of the HTTP response -- thus the annotation's name, @ResponseBody.
Of course, that resulted in every method in a Spring Boot REST API verbosely decorated with the @ResponseBody annotation. Eliminating the need to mind-numbingly add this annotation on every method in a RESTful API is the sole purpose of Spring's RestController.
When to use RestController vs. Controller
Spring's RestController does everything the Controller does, but it also implicitly adds the @ResponseBody annotation to every method that handles an HTTP request. That's it. That's the only technical difference between Spring's RestController and the Controller.
If you're creating a RESTful API with Spring Boot, decorate your class with the RestController annotation so that Spring automatically converts your JavaBeans into JSON or XML. If you want to markup your data in a more meaningful way, continue to use the Controller annotation, and allow the Spring MVC framework's rendering phase to do its work.
Cameron McKenzie has been a Java EE software engineer for 20 years. His current specialties include Agile development; DevOps; and container-based technologies such as Docker, Swarm and Kubernetes.