Chapter 1: Prerequisites for Learning REST API Annotations

To get started with this guide, you should have a foundational understanding of Spring REST API annotations like @RestController, @RequestMapping, @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PathVariable, @RequestParam, and @RequestBody. Familiarity with @RestController is particularly important for this discussion, while knowledge of the other annotations will also be advantageous. If you're not yet acquainted with these concepts, please check out the previous article for a comprehensive introduction. Once you're ready, come back here to continue.

You will also need the following setup to effectively follow along:

• A functional Java IDE and an API testing tool; I recommend using IntelliJ and Postman.
• A Spring REST API project generated via Spring Initializr. We will build upon the code from the prior article, but any Spring REST API project will suffice.

Chapter 2: Structuring the Appointment API

Regardless of whether you start with an empty project or utilize the shared repository, we'll create the Appointment API with a well-defined structure.

package api;

@RestController

@RequestMapping("/appointments")

public class AppointmentAPI {

@Autowired

private AppointmentService appointmentService;

// Listing appointments

@GetMapping("/")

public List<AppointmentDTO> list() {

return this.appointmentService.listAppointments();

}

// Other methods omitted for brevity...

// For the complete source code, refer to the accompanying repository.

}

The AppointmentDTO data structure:

package data;

public class AppointmentDTO {

public Long id;

public LocalDate date;

public String title;

public AppointmentDTO(Long id, LocalDate date, String title) {

this.id = id;

this.date = date;

this.title = title;

}

}

The AppointmentService implementation:

package service;

@Service

public class AppointmentService {

@Autowired

private AppointmentRepository appointmentRepository;

public List<AppointmentDTO> listAppointments() {

return this.appointmentRepository.findAll();

}

// Other methods omitted for brevity...

// For the complete source code, refer to the accompanying repository.

}

The AppointmentRepository for data management:

package repository;

@Repository

public class AppointmentRepository {

private List<AppointmentDTO> appointments;

private static Long lastId;

public AppointmentRepository() {

lastId = 1L;

appointments = new ArrayList<>();

appointments.add(new AppointmentDTO(lastId++, LocalDate.of(2024, 2, 1), "Visiting relative"));

appointments.add(new AppointmentDTO(lastId++, LocalDate.of(2024, 2, 16), "Finish tutorial"));

}

public List<AppointmentDTO> findAll() {

return this.appointments;

}

// Other methods omitted for brevity...

// For the complete source code, refer to the accompanying repository.

}

Chapter 3: Understanding @RestController Placement

You might ask, what significance does structure hold regarding the @RestController annotation? To clarify, this annotation can only be applied at the type level—meaning either a class or an interface, and never directly to fields or methods.

The placement of your type, specifically the package it resides in, is crucial. In our example, the @RestController is situated within the .api package, which is the initial point of contact for API web requests. This package is responsible for sanitizing and validating incoming data before passing it to subsequent packages like .service and .repository for further processing, ultimately returning a response if necessary.

While .api is a common designation for the API package, alternative names such as .web or .controller are also frequently used. Additionally, you can establish sub-packages within these to better organize related APIs or types.

Summary

In this article, we explored the appropriate placements for the @RestController annotation. We clarified that it must be applied at the type level and should be positioned in a primary package like .api, .web, or .controller, where API web requests are first received. This understanding is pivotal in distinguishing experienced developers from newcomers.

Explore the usage of Controller & RestController annotations in Spring Boot with this detailed REST tutorial.

Learn about Spring Boot annotations for REST APIs, including @RestController and @RequestMapping, in this comprehensive guide.