Mapping HTTP Methods to Controller Actions

1. From General to Specific: Why We Need More Than @RequestMapping

In the previous lesson, we used @RequestMapping("/greeting"). By default, this annotation maps to all HTTP methods. This means a client could technically send a GET, POST, PUT, or DELETE request to that URL, and the same getGreeting() method would be triggered.

For a robust and predictable API, this is not ideal. We want different actions to be handled by different methods. For example:

• A GET request to /employees should return a list of all employees.
• A POST request to /employees should create a new employee.

To achieve this, Spring provides specific annotations that are shortcuts for @RequestMapping pre-configured with a specific HTTP method.

As the article explains, the primary annotations we will use for our REST controllers are:

• @GetMapping: For retrieving resources (Read).
• @PostMapping: For creating new resources (Create).
• @PutMapping: For updating existing resources (Update).
• @DeleteMapping: For deleting resources (Delete).

Using these makes your code self-documenting and less prone to errors.

2. Building a CRUD API: A Practical Walkthrough

Theory is great, but the best way to learn is by doing. We are now going to build a full set of CRUD endpoints for managing a list of employees. The following video provides a comprehensive walkthrough.

While the video implements a complete application with service and repository layers, our focus for today is solely on the EmployeeController class. Pay close attention to the annotations used for each method.

A. Create: @PostMapping

To add a new resource to our system, we use the POST method. The @PostMapping annotation maps incoming HTTP POST requests to a handler method.

When creating a resource, the client usually sends the data for the new resource (e.g., the new employee's details) in the request body, typically as a JSON object. We use the @RequestBody annotation to tell Spring to convert this JSON into a Java object.

B. Read: @GetMapping

To retrieve resources, we use the GET method. We can use @GetMapping in two common ways:

1. Get all resources: A GET request to /employees returns a list of all employees.
2. Get a single resource by ID: A GET request to /employees/{id} returns the specific employee with that ID. To capture the id from the URL, we use the @PathVariable annotation.

Now, let's watch how to implement both of these "Read" operations.

Note: We'll dive deeper into @RequestBody and @PathVariable in upcoming lessons. For today, just understand their basic roles in getting data into our methods.

C. Update and Delete: @PutMapping and @DeleteMapping

Finally, to complete our CRUD functionality, we need to handle updates and deletions.

• @PutMapping: Maps PUT requests, used to update an existing resource. Like POST, it often uses @RequestBody for the updated data and @PathVariable to identify which resource to update.
• @DeleteMapping: Maps DELETE requests, used to remove a resource, typically identified by a @PathVariable.

Let's watch the final segment to complete our controller.

3. Hands-On: Build Your Own CRUD Controller

Now it's your turn to apply what you've learned to your first-api project. We'll create a simplified EmployeeController that stores data in memory (in a simple List) to keep the focus on the API layer.

1. Create an Employee class: In a new package com.mybackend.firstapi.model, create a simple Employee class. Since you know Java well, you can start with a basic structure for an employee record. For example:

   package com.mybackend.firstapi.model;
   
   // Add constructors, getters, and setters
   public class Employee {
       private long id;
       private String firstName;
       private String lastName;
       private String email;
   }
   

2. Create the EmployeeController: In your controller package, create a new EmployeeController class.

3. Implement the Controller Logic: Use the video and the code snippet below as a guide to build out your controller. Instead of a database, we'll use a List and a simple counter to manage IDs.

   package com.mybackend.firstapi.controller;
   
   import com.mybackend.firstapi.model.Employee;
   import org.springframework.web.bind.annotation.*;
   
   import java.util.ArrayList;
   import java.util.List;
   import java.util.concurrent.atomic.AtomicLong;
   
   @RestController
   @RequestMapping("/api/employees") // Base path for all methods in this controller
   public class EmployeeController {
   
       private final List<Employee> employees = new ArrayList<>();
       private final AtomicLong counter = new AtomicLong();
   
       public EmployeeController() {
           // Pre-populate with some data
           employees.add(new Employee(counter.incrementAndGet(), "John", "Doe", "john.doe@example.com"));
           employees.add(new Employee(counter.incrementAndGet(), "Jane", "Smith", "jane.smith@example.com"));
       }
   
       // 1. GET all employees
       @GetMapping
       public List<Employee> getAllEmployees() {
           return employees;
       }
   
       // 2. POST a new employee
       // Use Postman or a similar tool to send a POST request to http://localhost:8080/api/employees
       // with a JSON body like: {"firstName": "Sam", "lastName": "Jones", "email": "sam.j@email.com"}
       @PostMapping
       public Employee createEmployee(@RequestBody Employee newEmployee) {
           newEmployee.setId(counter.incrementAndGet());
           employees.add(newEmployee);
           return newEmployee;
       }
   
       // Add methods for GET by ID, PUT, and DELETE here.
       // Challenge yourself to write them based on the video and the patterns you've seen!
   }
   
   

4. Complete the Controller: Add the methods for:

   • GET /api/employees/{id}
   • PUT /api/employees/{id}
   • DELETE /api/employees/{id}

   You'll need to find the employee in the list for these operations. For the PUT method, find the employee and update their fields. For DELETE, find and remove them from the list.

5. Test Your API: Run your application. Since only GET requests can be easily made from a browser, you will need an API client like Postman to test POST, PUT, and DELETE. This is an essential tool for backend developers.

4. A Clean Example

You've now seen how the pieces fit together. For a final, clean reference, the official Spring guide provides a concise example of a complete controller.

Conclusion

Excellent work today! You have made a huge leap from a single, simple endpoint to building a controller that can perform all the fundamental CRUD operations.

Key Takeaways:

• For clear and maintainable REST APIs, use specific mapping annotations: @GetMapping, @PostMapping, @PutMapping, and @DeleteMapping.
• @GetMapping is for reading data.
• @PostMapping is for creating new data.
• @PutMapping is for updating existing data.
• @DeleteMapping is for deleting data.
• Annotations like @RequestBody and @PathVariable are used to get data from the incoming request, which is essential for making your endpoints dynamic.

What's Next?

In this lesson, we briefly introduced @RequestBody and @PathVariable out of necessity. They are crucial for handling client data. In our next lesson, we will focus entirely on handling request and response bodies using @RequestBody and @ResponseBody. You'll gain a much deeper understanding of how Spring deserializes incoming JSON into Java objects and serializes your Java objects back into JSON for the response.