1# Web Layer - Controllers & REST APIs
2 
3## REST Controller Pattern
4 
5```java
6@RestController
7@RequestMapping("/api/v1/users")
8@Validated
9@RequiredArgsConstructor
10public class UserController {
11    private final UserService userService;
12 
13    @GetMapping
14    public ResponseEntity<Page<UserResponse>> getUsers(
15            @PageableDefault(size = 20, sort = "createdAt") Pageable pageable) {
16        Page<UserResponse> users = userService.findAll(pageable);
17        return ResponseEntity.ok(users);
18    }
19 
20    @GetMapping("/{id}")
21    public ResponseEntity<UserResponse> getUser(@PathVariable Long id) {
22        UserResponse user = userService.findById(id);
23        return ResponseEntity.ok(user);
24    }
25 
26    @PostMapping
27    public ResponseEntity<UserResponse> createUser(
28            @Valid @RequestBody UserCreateRequest request) {
29        UserResponse user = userService.create(request);
30        URI location = ServletUriComponentsBuilder
31                .fromCurrentRequest()
32                .path("/{id}")
33                .buildAndExpand(user.id())
34                .toUri();
35        return ResponseEntity.created(location).body(user);
36    }
37 
38    @PutMapping("/{id}")
39    public ResponseEntity<UserResponse> updateUser(
40            @PathVariable Long id,
41            @Valid @RequestBody UserUpdateRequest request) {
42        UserResponse user = userService.update(id, request);
43        return ResponseEntity.ok(user);
44    }
45 
46    @DeleteMapping("/{id}")
47    @ResponseStatus(HttpStatus.NO_CONTENT)
48    public void deleteUser(@PathVariable Long id) {
49        userService.delete(id);
50    }
51}
52```
53 
54## Request DTOs with Validation
55 
56```java
57public record UserCreateRequest(
58    @NotBlank(message = "Email is required")
59    @Email(message = "Email must be valid")
60    String email,
61 
62    @NotBlank(message = "Password is required")
63    @Size(min = 8, max = 100, message = "Password must be 8-100 characters")
64    @Pattern(regexp = "^(?=.*[A-Z])(?=.*[a-z])(?=.*\\d).*$",
65             message = "Password must contain uppercase, lowercase, and digit")
66    String password,
67 
68    @NotBlank(message = "Username is required")
69    @Size(min = 3, max = 50)
70    @Pattern(regexp = "^[a-zA-Z0-9_]+$", message = "Username must be alphanumeric")
71    String username,
72 
73    @Min(value = 18, message = "Must be at least 18")
74    @Max(value = 120, message = "Must be at most 120")
75    Integer age
76) {}
77 
78public record UserUpdateRequest(
79    @Email(message = "Email must be valid")
80    String email,
81 
82    @Size(min = 3, max = 50)
83    String username
84) {}
85```
86 
87## Response DTOs
88 
89```java
90public record UserResponse(
91    Long id,
92    String email,
93    String username,
94    Integer age,
95    Boolean active,
96    LocalDateTime createdAt,
97    LocalDateTime updatedAt
98) {
99    public static UserResponse from(User user) {
100        return new UserResponse(
101            user.getId(),
102            user.getEmail(),
103            user.getUsername(),
104            user.getAge(),
105            user.getActive(),
106            user.getCreatedAt(),
107            user.getUpdatedAt()
108        );
109    }
110}
111```
112 
113## Global Exception Handling
114 
115```java
116@RestControllerAdvice
117@Slf4j
118public class GlobalExceptionHandler {
119 
120    @ExceptionHandler(ResourceNotFoundException.class)
121    public ResponseEntity<ErrorResponse> handleNotFound(
122            ResourceNotFoundException ex, WebRequest request) {
123        log.error("Resource not found: {}", ex.getMessage());
124        ErrorResponse error = new ErrorResponse(
125            HttpStatus.NOT_FOUND.value(),
126            ex.getMessage(),
127            request.getDescription(false),
128            LocalDateTime.now()
129        );
130        return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
131    }
132 
133    @ExceptionHandler(MethodArgumentNotValidException.class)
134    public ResponseEntity<ValidationErrorResponse> handleValidation(
135            MethodArgumentNotValidException ex) {
136        Map<String, String> errors = ex.getBindingResult()
137            .getFieldErrors()
138            .stream()
139            .collect(Collectors.toMap(
140                FieldError::getField,
141                error -> error.getDefaultMessage() != null
142                    ? error.getDefaultMessage()
143                    : "Invalid value"
144            ));
145 
146        ValidationErrorResponse response = new ValidationErrorResponse(
147            HttpStatus.BAD_REQUEST.value(),
148            "Validation failed",
149            errors,
150            LocalDateTime.now()
151        );
152        return new ResponseEntity<>(response, HttpStatus.BAD_REQUEST);
153    }
154 
155    @ExceptionHandler(DataIntegrityViolationException.class)
156    public ResponseEntity<ErrorResponse> handleDataIntegrity(
157            DataIntegrityViolationException ex, WebRequest request) {
158        log.error("Data integrity violation", ex);
159        ErrorResponse error = new ErrorResponse(
160            HttpStatus.CONFLICT.value(),
161            "Data integrity violation - resource may already exist",
162            request.getDescription(false),
163            LocalDateTime.now()
164        );
165        return new ResponseEntity<>(error, HttpStatus.CONFLICT);
166    }
167 
168    @ExceptionHandler(Exception.class)
169    public ResponseEntity<ErrorResponse> handleGlobalException(
170            Exception ex, WebRequest request) {
171        log.error("Unexpected error", ex);
172        ErrorResponse error = new ErrorResponse(
173            HttpStatus.INTERNAL_SERVER_ERROR.value(),
174            "An unexpected error occurred",
175            request.getDescription(false),
176            LocalDateTime.now()
177        );
178        return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
179    }
180}
181 
182record ErrorResponse(
183    int status,
184    String message,
185    String path,
186    LocalDateTime timestamp
187) {}
188 
189record ValidationErrorResponse(
190    int status,
191    String message,
192    Map<String, String> errors,
193    LocalDateTime timestamp
194) {}
195```
196 
197## Custom Validation
198 
199```java
200@Target({ElementType.FIELD, ElementType.PARAMETER})
201@Retention(RetentionPolicy.RUNTIME)
202@Constraint(validatedBy = UniqueEmailValidator.class)
203public @interface UniqueEmail {
204    String message() default "Email already exists";
205    Class<?>[] groups() default {};
206    Class<? extends Payload>[] payload() default {};
207}
208 
209@Component
210@RequiredArgsConstructor
211public class UniqueEmailValidator implements ConstraintValidator<UniqueEmail, String> {
212    private final UserRepository userRepository;
213 
214    @Override
215    public boolean isValid(String email, ConstraintValidatorContext context) {
216        if (email == null) return true;
217        return !userRepository.existsByEmail(email);
218    }
219}
220```
221 
222## WebClient for External APIs
223 
224```java
225@Configuration
226public class WebClientConfig {
227    @Bean
228    public WebClient webClient(WebClient.Builder builder) {
229        return builder
230            .baseUrl("https://api.example.com")
231            .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
232            .filter(logRequest())
233            .build();
234    }
235 
236    private ExchangeFilterFunction logRequest() {
237        return ExchangeFilterFunction.ofRequestProcessor(request -> {
238            log.info("Request: {} {}", request.method(), request.url());
239            return Mono.just(request);
240        });
241    }
242}
243 
244@Service
245@RequiredArgsConstructor
246public class ExternalApiService {
247    private final WebClient webClient;
248 
249    public Mono<ExternalDataResponse> fetchData(String id) {
250        return webClient
251            .get()
252            .uri("/data/{id}", id)
253            .retrieve()
254            .onStatus(HttpStatusCode::is4xxClientError, response ->
255                Mono.error(new ResourceNotFoundException("External resource not found")))
256            .onStatus(HttpStatusCode::is5xxServerError, response ->
257                Mono.error(new ServiceUnavailableException("External service unavailable")))
258            .bodyToMono(ExternalDataResponse.class)
259            .timeout(Duration.ofSeconds(5))
260            .retry(3);
261    }
262}
263```
264 
265## CORS Configuration
266 
267```java
268@Configuration
269public class WebConfig implements WebMvcConfigurer {
270 
271    @Override
272    public void addCorsMappings(CorsRegistry registry) {
273        registry.addMapping("/api/**")
274            .allowedOrigins("http://localhost:3000", "https://example.com")
275            .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
276            .allowedHeaders("*")
277            .allowCredentials(true)
278            .maxAge(3600);
279    }
280}
281```
282 
283## Quick Reference
284 
285| Annotation | Purpose |
286|------------|---------|
287| `@RestController` | Marks class as REST controller (combines @Controller + @ResponseBody) |
288| `@RequestMapping` | Maps HTTP requests to handler methods |
289| `@GetMapping/@PostMapping` | HTTP method-specific mappings |
290| `@PathVariable` | Extracts values from URI path |
291| `@RequestParam` | Extracts query parameters |
292| `@RequestBody` | Binds request body to method parameter |
293| `@Valid` | Triggers validation on request body |
294| `@RestControllerAdvice` | Global exception handling for REST controllers |
295| `@ResponseStatus` | Sets HTTP status code for method |
296