REST Controller Basics

@RestController
@RequestMapping("/api/v1/users")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

    @GetMapping
    public PagedModel<UserResponse> findAll(@PageableDefault(size = 20) Pageable pageable) {
        return new PagedModel<>(userService.findAll(pageable));    // stable JSON shape
    }

    @GetMapping("/{id}")
    public UserResponse findById(@PathVariable Long id) {
        return userService.findById(id);                           // 200, body is the DTO
    }

    @PostMapping
    public ResponseEntity<UserResponse> create(@RequestBody @Valid CreateUserRequest request) {
        UserResponse created = userService.create(request);
        URI location = ServletUriComponentsBuilder.fromCurrentRequest()
            .path("/{id}").buildAndExpand(created.id()).toUri();   // .../api/v1/users/42
        return ResponseEntity.created(location).body(created);     // 201 + Location
    }

    @PutMapping("/{id}")
    public UserResponse replace(@PathVariable Long id, @RequestBody @Valid UpdateUserRequest request) {
        return userService.update(id, request);
    }

    @PatchMapping("/{id}")
    public UserResponse patch(@PathVariable Long id, @RequestBody @Valid PatchUserRequest request) {
        return userService.patch(id, request);
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)                         // 204, no ResponseEntity needed
    public void delete(@PathVariable Long id) {
        userService.delete(id);
    }
}

// Server-rendered pages: return a view name
@Controller
public class PageController {

    private final UserService userService;
    public PageController(UserService userService) { this.userService = userService; }

    @GetMapping("/users")
    public String usersPage(Model model) {
        model.addAttribute("users", userService.findAll());
        return "users";                    // resolved to templates/users.html
    }
}

// JSON API: every method writes the return value to the body
@RestController                            // = @Controller + @ResponseBody
@RequestMapping("/api/v1/users")
public class UserApiController {

    @GetMapping
    public List<UserResponse> findAll() { ... }   // no @ResponseBody needed
}

@RestController
@RequestMapping("/api/v1/orders")
public class OrderController {

    // Content negotiation: consumes/produces narrow what the endpoint accepts and returns.
    // A request with the wrong Content-Type gets 415, an unsatisfiable Accept gets 406.
    @PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<OrderResponse> create(@RequestBody @Valid CreateOrderRequest req) { ... }

    // Triggering an action that is not CRUD: POST on a sub-resource
    @PostMapping("/{id}/cancel")
    public OrderResponse cancel(@PathVariable Long id) { ... }
}

// Quick reference
//   GET    /orders        200 + list        GET    /orders/{id}   200, or 404 if missing
//   POST   /orders        201 + Location    PUT    /orders/{id}   200 (or 204), 404 if missing
//   PATCH  /orders/{id}   200               DELETE /orders/{id}   204 (404 or 204 if already gone)
//   Validation failure    400 (or 422)      Not authenticated 401, not allowed 403
//   Duplicate / conflict  409               Wrong Content-Type 415

public record CreateUserRequest(
    @NotBlank @Size(max = 100) String name,
    @NotBlank @Email String email,
    @NotBlank @Size(min = 8) String password) {}

public record UserResponse(Long id, String name, String email) {
    static UserResponse from(UserEntity u) { return new UserResponse(u.getId(), u.getName(), u.getEmail()); }
}

@GetMapping("/search")
public PagedModel<UserResponse> search(
        @RequestParam(required = false) String name,                           // ?name=ali
        @RequestParam(defaultValue = "true") boolean active,                   // ?active=false
        @RequestParam(required = false)
            @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate since,    // ?since=2026-01-31
        @RequestHeader(name = "X-Request-Id", required = false) String requestId,
        @PageableDefault(size = 20, sort = "name") Pageable pageable) {        // ?page=0&size=20&sort=name,asc
    return new PagedModel<>(userService.search(name, active, since, pageable));
}

@RestController
@RequestMapping("/api/v1/documents")
public class DocumentController {

    private final DocumentService docService;
    public DocumentController(DocumentService docService) { this.docService = docService; }

    // ETag: Spring returns 304 automatically when If-None-Match matches
    @GetMapping("/{id}")
    public ResponseEntity<DocumentResponse> findById(@PathVariable Long id) {
        DocumentResponse doc = docService.findById(id);
        return ResponseEntity.ok()
            .eTag(String.valueOf(doc.version()))                 // quotes are added for you
            .cacheControl(CacheControl.maxAge(Duration.ofMinutes(5)).cachePrivate())
            .body(doc);
    }

    // Download: Resource body, proper disposition, Range requests supported
    @GetMapping("/{id}/export")
    public ResponseEntity<Resource> export(@PathVariable Long id) {
        Resource file = docService.export(id);
        return ResponseEntity.ok()
            .contentType(MediaType.APPLICATION_PDF)
            .header(HttpHeaders.CONTENT_DISPOSITION,
                    ContentDisposition.attachment().filename("doc-" + id + ".pdf").build().toString())
            .cacheControl(CacheControl.noStore())
            .body(file);
    }
}

@RestControllerAdvice
class ApiExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    ProblemDetail notFound(UserNotFoundException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
        pd.setTitle("User not found");
        return pd;
    }

    @ExceptionHandler(EmailAlreadyUsedException.class)
    ProblemDetail conflict(EmailAlreadyUsedException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, "Email is already registered");
        pd.setTitle("Conflict");
        return pd;
    }
}

// Response
// HTTP/1.1 404   Content-Type: application/problem+json
// { "type": "about:blank", "title": "User not found", "status": 404,
//   "detail": "No user with id 42", "instance": "/api/v1/users/42" }

// Wrong: repository and rules in the controller; check-then-insert race
@PostMapping
public ResponseEntity<UserResponse> create(@RequestBody CreateUserRequest req) {
    if (userRepository.existsByEmail(req.email())) throw new ConflictException("Email taken");
    UserEntity user = userRepository.save(new UserEntity(req.name(), req.email()));
    return ResponseEntity.status(201).body(UserResponse.from(user));
}

// Right: the controller maps HTTP; the service owns the rule and the constraint handling
@PostMapping
public ResponseEntity<UserResponse> create(@RequestBody @Valid CreateUserRequest req) {
    UserResponse created = userService.create(req);
    URI location = ServletUriComponentsBuilder.fromCurrentRequest()
        .path("/{id}").buildAndExpand(created.id()).toUri();
    return ResponseEntity.created(location).body(created);
}

// In the service
@Transactional
public UserResponse create(CreateUserRequest req) {
    try {
        return UserResponse.from(userRepository.saveAndFlush(UserEntity.from(req)));   // unique index on email
    } catch (DataIntegrityViolationException e) {
        throw new EmailAlreadyUsedException(req.email());                              // handler maps to 409
    }
}