Building REST Controllers with Spring

1. From Request to Code: The Role of a Controller

Remember from our first module how the DispatcherServlet acts as a central hub, receiving all incoming requests? Its main job is to figure out which code should handle that specific request. In Spring, the components responsible for handling these requests are called controllers.

A controller is simply a Java class that listens for requests at specific URLs and contains methods that execute in response.

To get a feel for how this works in Spring, let's watch a brief introduction.

As the video explains, we will create a simple Java class and use annotations to give it the "superpower" of being a web request handler.

2. Introducing @RestController

To turn a plain Java class into a web controller, Spring provides a set of special annotations. For building REST APIs that return data (like JSON) rather than HTML pages, the primary annotation is @RestController.

@RestController is a specialized annotation that tells Spring two things:

1. This class is a controller and should be scanned for request mappings.
2. The return value of its methods should be written directly into the HTTP response body. This is crucial for APIs, as we want to send back data, not render a view.

@Controller vs. @RestController

You might also see @Controller used in Spring applications. What's the difference? This is an important distinction that aligns with your goal of understanding what happens "under the hood".

• @Controller: This is the original annotation for Spring MVC. By default, its methods are expected to return a String that represents the name of a view (e.g., an HTML template) to be rendered.
• @RestController: This is a convenience annotation that combines @Controller and another annotation, @ResponseBody. The @ResponseBody part is what automatically tells Spring to serialize the method's return object into the response body (e.g., as JSON).

Since our goal is to build REST APIs, we will almost always use @RestController.

This short video explains the difference clearly.

To reinforce this, the following image provides a handy comparison table.

3. Mapping URLs with @RequestMapping

Now that we have a class marked as a @RestController, how do we link a specific URL path to a method inside that class? For this, we use the @RequestMapping annotation.

You apply @RequestMapping to a method and provide it with the URL path you want to map.

For example:

@RequestMapping("/hello")
public String sayHello() {
    return "Hello, World!";
}

When Spring sees this, it understands that any HTTP request to http://localhost:8080/hello should trigger the sayHello() method. Because the class is annotated with @RestController, the returned String ("Hello, World!") will be sent back as the plain text response.

Let's see this in action.

An important point mentioned in the video is that @RequestMapping by default maps to GET requests, which is what your browser makes when you type a URL. We'll cover other HTTP methods like POST in the next lesson.

4. Hands-On: Your First API Endpoint

It's time to apply this to the first-api project you created in the last lesson.

1. Open your project in your IDE.

2. Create a new package: Inside your main package (com.mybackend.firstapi), create a new sub-package named controller. It's good practice to organize your classes by their function.

3. Create a new Java class: Inside the controller package, create a new class named GreetingController.

4. Add the annotations and method: Add the @RestController annotation to the class and create a method with a @RequestMapping. Your final code should look like this:

   package com.mybackend.firstapi.controller;
   
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   @RestController
   public class GreetingController {
   
       @RequestMapping("/greeting")
       public String getGreeting() {
           return "Hello from your first Spring Boot API!";
       }
   }
   

5. Run the application: Just as you did in the previous lesson, run the FirstApiApplication main class.

6. Test your endpoint: Once the server starts (on port 8080), open a web browser and navigate to http://localhost:8080/greeting.

You should see the text "Hello from your first Spring Boot API!" in your browser. You've just created and successfully called your first API endpoint!

How did Spring find your controller?

You might wonder how Spring automatically detected your GreetingController class. This is due to the component scanning feature we touched upon in the last lesson. The @SpringBootApplication annotation on your main class includes @ComponentScan, which directs Spring to scan the current package and all its sub-packages for classes annotated with stereotypes like @RestController, @Service, @Repository, etc., and register them as Spring beans.

5. Looking at a Complete Controller

Our greeting controller is simple. In a real application, controllers manage a specific resource (like "Employees" or "Products").

This EmployeeController example shows how one controller can have multiple methods to handle all the operations for a single resource. We will build a controller just like this over the next few lessons.

Conclusion

Fantastic work today! You've bridged the gap between a running server and a functional API endpoint. This is a critical milestone in your backend development journey.

Key Takeaways:

• Controllers are Java classes that handle incoming web requests.
• @RestController is the primary annotation for building REST APIs. It marks a class as a controller and ensures method return values are serialized directly to the response body.
• @RequestMapping("/path") is used on methods to map them to a specific URL path.
• Spring Boot's component scanning automatically detects and registers your controller classes when the application starts.

What's Next?

So far, we've used @RequestMapping for a simple GET request. However, REST APIs use various HTTP methods to perform different actions (Create, Read, Update, Delete). In our next lesson, we will dive into more specific mapping annotations like @GetMapping, @PostMapping, @PutMapping, and @DeleteMapping to build a full set of CRUD operations for a resource.