Request & response conventions

Overview

This document defines conventions for API request/response DTOs: package structure, naming, and @JsonFormat annotation usage.

Key Principle: Separate API DTOs into dto/request/ and dto/response/ packages. Use correct @JsonFormat use-site targets.

Never return entities

IMPORTANT: Never return JPA entities directly as API responses. Always convert to a response DTO. Exposing entities leaks internal structure, bypasses timezone conversion, and couples the API contract to the database schema.

// Bad: Returning entity directly
@GetMapping("/{id}")
fun getById(@PathVariable id: Long): ResponseEntity<ApiResource<Holiday>> =
    ApiResource.success(holidayService.findById(id))