Lesson 1: Controller Basics - part 1

1. Goals

In this module, we’re going to take a closer look at some of the core Spring MVC annotations that are useful not only when building a REST API, but also when building a more traditional MVC application.

2. Lesson Notes

The relevant module you need to import when you're starting with this lesson is: m8-controller-basics-start

If you want have a look at the fully implemented lesson, as a reference, feel free to import: m8-controller-basics-end

2.1. Overview

Let’s start with the primary annotations that actually define our controllers:

@Controller
@RestController

We’ve already seen these core annotations. For example, when we were implementing our first, simple controller, we’ve used @RestController. Also, when we were implementing our MVC application, we’ve used @Controller.

Let's discuss the exact differences between them.

@Controller doesn’t make any assumption about the style of application we’re building. It doesn’t matter if we’re building a REST API or a traditional, MVC-style of application.

@RestController, on the other hand, becomes handy when we’re building a REST API. In this case, typically, we want to marshall our responses, resources directly to the HTTP response body. So, we’ll need to use the @ResponseBody annotation to do that.

The point is that putting that on each and every method gets repetitive. So, the @RestController annotation simply bundles @ResponseBody so that we don’t have to manually add it each time.

Note that both @Controller and @RestController are stereotype annotations because they are a specialization of Spring’s @Component stereotype annotation. These give more meaning to a controller class to clearly indicate whether it's an MVC or REST-style controller.

Another important aspect of handling the requests is the @RequestMapping annotation. It helps us map our method with an HTTP verb, a request path and a few other details about the request.

Spring MVC introduced a few simple shorthand annotations that we can use instead of the more open, low-level @RequestMapping:

@GetMapping
@PostMapping
@PutMapping
@DeleteMapping

2.2. Controllers

Our goal here is to create a simple CRUD REST API for our domain.

Let’s open ProjectController that we’ve already worked on earlier in the course:

We’re already using @RestController and @RequestMapping and we already have two endpoints declared here: one for the getting a project by its id and the other for creating a new project.

**2.3. @RequestMapping at the Controller Level**

Using an annotation and really understanding it - are two very different things. Let’s have a closer look at @RequestMapping.

It is defined not on an individual method, but at the base controller level.

Generally speaking, the mappings logically belong on controller's methods. Why do we have it on the controller?

That’s because we can actually combine multiple annotations at multiple levels. This fact allows Spring to merge them behind the scenes to form our final mapping, at the method level.

That’s hugely powerful. Simply put, when we define this at the controller level, it will apply to all methods defined in the controller as a baseline of common configuration which we can then refine at the method level.

2.4. Example Methods: Get By Id

We can see how the above-mentioned idea of the mapping refinement works in the get by id method. The base annotation sets the URL to /projects and this method-level annotation sets it to /{id}.Spring will combine them into /projects/{id}.

Also, notice this is using the @GetMapping annotation which is basically a more refined version of @RequestMapping, pre-selecting the GET HTTP verb for the mapping: