REST API Conventions

// ❌ BAD — all the common mistakes in one controller

@RestController
@RequestMapping("/orders")          // preserve the project route prefix
public class OrderController {

    @Autowired                       // field injection
    private OrderRepository orderRepository;  // direct repo, no service layer

    @PostMapping
    public Order createOrder(@RequestBody CreateOrderRequest request) { // returns entity directly
        Order order = new Order();   // no factory method
        order.setEmail(request.getEmail());
        return orderRepository.save(order); // entity leakage; missing creation status
    }

    @GetMapping("/{id}")
    public Map<String, Object> getOrder(@PathVariable Long id) { // ID type is not the problem; authorization still matters
        Optional<Order> order = orderRepository.findById(id);
        if (!order.isPresent()) {
            return Map.of("error", "not found"); // ad-hoc error, no status code
        }
        return Map.of("data", order.get()); // raw map, entity leakage
    }

    @GetMapping
    public List<Order> getAllOrders() { // no pagination, returns all rows
        return orderRepository.findAll();
    }

    @DeleteMapping("/{id}")
    public String delete(@PathVariable Long id) {
        orderRepository.deleteById(id);
        return "deleted"; // 200 with body instead of 204
    }
}

// ✅ GOOD — proper response envelope, correct status, no entity leakage

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

    private final OrderService orderService;

    @PostMapping
    public ResponseEntity<ApiResponse<OrderResponse>> create(
        @Valid @RequestBody CreateOrderRequest request
    ) {
        Order order = orderService.createOrder(request);
        return ResponseEntity
            .status(HttpStatus.CREATED)
            .body(ApiResponse.ok(OrderResponse.from(order)));
    }

    @GetMapping("/{id}")
    public ApiResponse<OrderResponse> getById(@PathVariable UUID id) {
        return ApiResponse.ok(OrderResponse.from(orderService.findById(id)));
    }

    @GetMapping
    public ApiResponse<PageResponse<OrderResponse>> list(Pageable pageable) {
        return ApiResponse.ok(PageResponse.from(orderService.findAll(pageable).map(OrderResponse::from)));
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void delete(@PathVariable UUID id) {
        orderService.delete(id);
    }
}

package com.example.common.api;

import com.fasterxml.jackson.annotation.JsonInclude;
import java.time.Instant;
import java.util.List;

@JsonInclude(JsonInclude.Include.NON_NULL)
public record ApiResponse<T>(
    boolean success,
    T data,
    ApiError error,
    Instant timestamp
) {
    public static <T> ApiResponse<T> ok(T data) {
        return new ApiResponse<>(true, data, null, Instant.now());
    }

    public static <T> ApiResponse<T> error(String code, String message) {
        return new ApiResponse<>(false, null,
            new ApiError(code, message, List.of()), Instant.now());
    }

    public static <T> ApiResponse<T> validationError(List<String> violations) {
        return new ApiResponse<>(false, null,
            new ApiError("VALIDATION_FAILED", "Input validation failed", violations), Instant.now());
    }

    public record ApiError(String code, String message, List<String> details) {}
}

package com.example.common.exception;

import com.example.common.api.ApiResponse;
import jakarta.persistence.EntityNotFoundException;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.HttpStatusCode;
import org.springframework.http.ResponseEntity;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

import java.util.List;

/**
 * Extends ResponseEntityExceptionHandler so Spring MVC's own client errors keep their
 * status: malformed JSON (400), wrong method (405), bad path variable (400), unknown
 * URL (404), unsupported media type (415). Without it, the Exception.class catch-all
 * below turns all of them into 500.
 */
@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(EntityNotFoundException.class)
    public ResponseEntity<ApiResponse<Void>> handleNotFound(EntityNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
            .body(ApiResponse.error("NOT_FOUND", ex.getMessage()));
    }

    // @PreAuthorize denials are thrown inside the dispatcher, so the security filter's
    // AccessDeniedHandler never sees them — map them here or the catch-all returns 500.
    @ExceptionHandler(AccessDeniedException.class)
    public ResponseEntity<ApiResponse<Void>> handleAccessDenied(AccessDeniedException ex) {
        return ResponseEntity.status(HttpStatus.FORBIDDEN)
            .body(ApiResponse.error("FORBIDDEN", "Access denied"));
    }

    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(
            MethodArgumentNotValidException ex, HttpHeaders headers, HttpStatusCode status, WebRequest request) {
        List<String> violations = ex.getBindingResult().getFieldErrors().stream()
            .map(e -> e.getField() + ": " + e.getDefaultMessage())
            .toList();
        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
            .body(ApiResponse.validationError(violations));
    }

    // Every other framework exception handled by the superclass ends up here: keep its
    // status and headers (e.g. Allow on 405), but return the project's envelope.
    @Override
    protected ResponseEntity<Object> handleExceptionInternal(
            Exception ex, Object body, HttpHeaders headers, HttpStatusCode status, WebRequest request) {
        HttpStatus resolved = HttpStatus.resolve(status.value());
        String code = resolved != null ? resolved.name() : "HTTP_" + status.value();
        return ResponseEntity.status(status).headers(headers)
            .body(ApiResponse.error(code, "Request could not be processed"));
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiResponse<Void>> handleGeneric(Exception ex) {
        log.error("Unhandled exception", ex);
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(ApiResponse.error("INTERNAL_ERROR", "An unexpected error occurred"));
    }
}

package com.example.common.api;

import java.util.List;
import org.springframework.data.domain.Page;

public record PageResponse<T>(
        List<T> content, int page, int size, long totalElements, int totalPages, boolean last) {
    public PageResponse {
        content = List.copyOf(content);
    }

    public static <T> PageResponse<T> from(Page<T> source) {
        return new PageResponse<>(source.getContent(), source.getNumber(), source.getSize(),
            source.getTotalElements(), source.getTotalPages(), source.isLast());
    }
}