API에서의 타임스탬프: 모범 사례

API 타임스탬프의 황금 원칙

항상 명시적 UTC 오프셋이 있는 ISO 8601 / RFC 3339 형식으로 반환하세요. API 응답의 모든 타임스탬프는 "2024-03-01T14:30:00Z" 또는 "2024-03-01T14:30:00+09:00" 형태여야 합니다 — 날짜 문자열만, 모호한 현지 시간, 단위 없는 Unix 정수는 안 됩니다.

타임스탬프 형식 비교

// 나쁜 예: 모호한 현지 시간
{"created_at": "2024-03-01 14:30:00"}

// 나쁜 예: 단위 미명시 Unix 타임스탬프
{"created_at": 1709300200}   // 초? 밀리초?

// 좋은 예: RFC 3339 UTC
{"created_at": "2024-03-01T14:30:00Z"}

// 좋은 예: 단위 명시
{"created_at_ms": 1709300200000}

API 전반의 일관성

• 하나의 형식을 선택해 모든 곳에 사용하세요 — 일부 엔드포인트에는 ISO 문자열, 다른 곳에는 Unix 정수를 혼용하지 마세요.
• 일관된 필드 이름 패턴 사용: created_at, updated_at, deleted_at.
• 시간대 정보를 항상 포함하세요.

타임스탬프 기반 커서 페이지네이션

// 응답
{
  "data": [...],
  "next_cursor": "2024-03-01T14:30:00Z",
  "has_more": true
}

// 다음 요청
GET /api/events?before=2024-03-01T14:30:00Z&limit=20

날짜 범위 필터링

# REST API — ISO 8601 허용
GET /api/orders?created_after=2024-03-01T00:00:00Z&created_before=2024-03-31T23:59:59Z

# Django — 안전한 타임스탬프 파싱
from django.utils.dateparse import parse_datetime
from django.utils import timezone

def get_queryset(self):
    after = self.request.query_params.get("created_after")
    if after:
        dt = parse_datetime(after)
        if dt and timezone.is_naive(dt):
            dt = timezone.make_aware(dt, timezone.utc)
        queryset = queryset.filter(created_at__gte=dt)