Building REST APIs with Spring MVC

What You Will Learn

• The DispatcherServlet request flow.
• @RestController and @RequestMapping (class + method level).
• @GetMapping, @PostMapping, @PutMapping, @PatchMapping, @DeleteMapping.
• Binding input: @PathVariable, @RequestParam, @RequestBody, @RequestHeader.
• Shaping output with ResponseEntity and HTTP status codes.
• Why the API uses request/response DTOs and never returns entities.

Chapter Structure

2.1 The Request Flow

Every HTTP request to the backend passes through the same pipeline:

The DispatcherServlet is the "front controller" that Spring Boot registers automatically. You never see it; you only write the handler methods.

2.2 Mapping URLs to Methods

Here is the whole of PatientController:

@RestController
@RequestMapping("/api/patients")
@RequiredArgsConstructor
public class PatientController {

    private final PatientService patientService;

    @GetMapping
    public ResponseEntity<List<PatientResponse>> getAllPatients(
            @RequestParam(required = false) String search) {
        return ResponseEntity.ok(patientService.getAllPatients(search));
    }

    @GetMapping("/{id}")
    public ResponseEntity<PatientResponse> getPatientById(@PathVariable Long id) {
        return ResponseEntity.ok(patientService.getPatientById(id));
    }

    @PostMapping
    public ResponseEntity<PatientResponse> createPatient(@RequestBody @Valid PatientRequest request) {
        return ResponseEntity.status(HttpStatus.CREATED).body(patientService.createPatient(request));
    }

    @PutMapping("/{id}")
    public ResponseEntity<PatientResponse> updatePatient(
            @PathVariable Long id, @RequestBody @Valid PatientRequest request) {
        return ResponseEntity.ok(patientService.updatePatient(id, request));
    }
}

• @RestController = @Controller + @ResponseBody. The second part means "return values are the response body", not view names.
• @RequestMapping("/api/patients") on the class is a prefix for every method in it.
• @GetMapping("/{id}") is shorthand for @RequestMapping(method = GET, path = "/{id}"). The full path becomes /api/patients/{id}.

2.3 Reading Input

2.3.1 @PathVariable — a value from the URL path

@GetMapping("/{id}")
public ResponseEntity<PatientResponse> getPatientById(@PathVariable Long id) { ... }

// GET /api/patients/42   →   id = 42L

The {id} template segment and the parameter name line up. Spring also converts the text "42" to Long for you; a non-numeric value produces a 400.

2.3.2 @RequestParam — a query-string value

@GetMapping
public ResponseEntity<List<PatientResponse>> getAllPatients(
        @RequestParam(required = false) String search) { ... }

// GET /api/patients            → search = null
// GET /api/patients?search=rao → search = "rao"

required = false makes the parameter optional. ReportsController also uses defaultValue:

@GetMapping("/top-medicines")
public ResponseEntity<List<TopMedicineResponse>> getTopMedicines(
        @RequestParam(defaultValue = "5") int limit,
        @RequestParam(required = false) Long branchId) { ... }

2.3.3 @RequestBody — the JSON payload

@PostMapping
public ResponseEntity<PatientResponse> createPatient(
        @RequestBody @Valid PatientRequest request) { ... }

The request's JSON body is deserialised by Jackson into a PatientRequest object, field by field. Adding @Valid tells Spring to run Bean Validation on it before the method body executes (Chapter 5).

2.3.4 @RequestHeader — a header value

From AuthController.logout:

@PostMapping("/logout")
public ResponseEntity<Void> logout(
        @RequestHeader(value = "Authorization", required = false) String authHeader) {

    if (authHeader == null || !authHeader.startsWith("Bearer ")) {
        throw new ResponseStatusException(HttpStatus.UNAUTHORIZED, "Missing bearer token");
    }
    authService.logout(authHeader.substring(7));
    return ResponseEntity.noContent().build();
}

2.4 Producing Output

A handler can return a plain object (Spring wraps it in a 200) or a ResponseEntity<T> when it needs to control the status code or headers. This project always uses ResponseEntity for consistency:

return ResponseEntity.ok(body);                          // 200 OK + body
return ResponseEntity.status(HttpStatus.CREATED).body(x); // 201 Created + body
return ResponseEntity.noContent().build();                // 204 No Content, no body

2.5 DTOs — Why the API Never Returns an Entity

Look at the patient package: there is a Patient entity, a PatientRequest (input) and a PatientResponse (output). The controller speaks only in the latter two. This separation is deliberate.

@Data
public class PatientRequest {
    @NotBlank @Size(max = 80) private String firstName;
    @NotBlank @Size(max = 80) private String lastName;
    private Gender gender;
    private LocalDate dob;
    // ... note: no id, no patientCode, no uhid, no createdAt
}

@Data
@AllArgsConstructor
public class PatientResponse {
    private Long id;
    private String patientCode;   // server-generated, safe to expose
    private String uhid;
    private String firstName;
    // ...
}

2.6 Content Negotiation (briefly)

Spring picks a converter using the request's Accept header and the body's Content-Type. Because only Jackson is configured, everything is application/json. A POST without Content-Type: application/json will fail to bind @RequestBody with a 415 Unsupported Media Type.

Quick Concept Map

Common Mistakes

1. Two handlers mapped to the same verb + path → ambiguous mapping, startup fails.
2. Forgetting @RequestBody, so Spring tries to bind the JSON fields from query parameters and they come out null.
3. Returning the JPA entity directly and hitting LazyInitializationException or leaking a field.
4. Using @PathVariable when the name does not match the URI template variable (fix with @PathVariable("id")).
5. Returning 201 Created from a GET, or 200 from a resource-creating POST — pick the status that matches the semantics.
6. Putting business rules in the controller instead of delegating to a service.
7. Client omits Content-Type: application/json and is surprised by a 415.

Revision Questions

1. What is the DispatcherServlet and who registers it?
2. What does @RestController add over @Controller?
3. How is the full path of PatientController.getPatientById assembled?
4. Give the source of data for @PathVariable, @RequestParam, @RequestBody, @RequestHeader.
5. How do you return 201 Created with a body?
6. Give three concrete reasons not to return the entity.
7. Why does PatientRequest have no patientCode field?
8. What HTTP status results from a request body that fails @Valid?

Practice

Chapter Wrap-Up

Spring MVC routes a request to a controller method by verb and path, fills the method's parameters from the path, query, body and headers, and serialises the return value to JSON. Controllers in this project stay deliberately thin: bind, delegate, wrap. The API speaks in DTOs so its contract is independent of the database schema and nothing private leaks out.

Teaching note: code is quoted from the hospital-erp backend (Spring Boot 4). Some snippets are lightly trimmed with // ... for focus.