API 응답에 createdAt과 updatedAt을 둘 다 넣는 이유

API 응답을 설계할 때 createdAt과 updatedAt 중 하나만 넣어도 되는 거 아닌가 싶을 때가 있다. 특히 초기에 빠르게 만들다 보면 어차피 지금은 업데이트 기능이 없으니까 createdAt만 있어도 된다고 생각하기 쉽다.

그런데 나중에 updatedAt을 추가하려면 기존 레코드에 값이 없어서 마이그레이션이 필요하고, 클라이언트가 이미 createdAt으로 정렬 로직을 짜놓은 경우 변경 비용이 생긴다.

두 필드가 답하는 질문이 다르다

• createdAt: "이 항목이 언제 만들어졌나?" → 생성 시점, 최초 등록일 표시에 쓴다.
• updatedAt: "이 항목이 마지막으로 바뀐 게 언제인가?" → 최신 여부 판단, 캐시 무효화, 동기화에 쓴다.

특히 클라이언트 측 캐싱이나 오프라인 동기화를 구현할 때 updatedAt은 필수다. "마지막 동기화 이후 바뀐 항목만 가져와라"라는 요청은 updatedAt이 없으면 구현하기 어렵다.

GET /api/posts?updatedAfter=2025-06-01T00:00:00Z

DB 스키마에서 두 필드 관리

Prisma 예시다.

model Post {
  id        String   @id @default(cuid())
  title     String
  content   String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt      // Prisma가 자동으로 갱신
}

@updatedAt을 붙이면 레코드가 수정될 때마다 Prisma가 자동으로 updatedAt을 현재 시각으로 갱신한다. SQL로 직접 관리한다면 트리거나 ON UPDATE CURRENT_TIMESTAMP로 처리한다.

API 응답에서의 형식

{
  "id": "cuid123",
  "title": "제목",
  "createdAt": "2025-01-15T09:23:41.000Z",
  "updatedAt": "2025-06-20T14:05:12.000Z"
}

타임스탬프는 ISO 8601 형식의 UTC로 반환하는 게 낫다. 클라이언트가 필요에 따라 로컬 시간으로 변환할 수 있고, 비교 연산도 문자열 그대로 할 수 있다.

처음부터 둘 다 넣어두면 좋은 이유

updatedAt을 나중에 추가하면 기존 레코드의 값이 없다. null로 두거나, createdAt과 동일하게 백필하거나 둘 중 하나인데 어느 쪽이든 부자연스러운 데이터가 남는다. 처음부터 두 필드를 같이 넣어두면 이런 결정을 나중으로 미루지 않아도 된다.