REST API에서 날짜 필터가 이상할 때 확인할 것

REST API에서 "2024-01-01부터 2024-01-31까지의 데이터를 달라"고 요청했는데, 기대와 다른 결과가 나올 때가 있다. 대부분은 타임존, 날짜 형식, 경계값 처리의 차이 때문이다.

요청을 정확히 어떻게 보냈는지 기록한다

먼저 실제 요청을 확인해야 한다:

# cURL로 API 호출 기록
curl -i 'https://api.example.com/items?start_date=2024-01-01&end_date=2024-01-31'

응답 상태 코드와 응답 body를 다 본다. 특히 다음을 확인하자:

• HTTP 상태 코드 (200, 400, 500 등)
• 응답 body의 실제 데이터 개수
• 응답에 포함된 데이터의 타임스탬프

API 서버가 기대하는 날짜 형식 확인

서버가 지원하는 형식을 문서나 예제에서 찾아보자:

# ISO 8601 형식 (권장)
https://api.example.com/items?start_date=2024-01-01T00:00:00Z

# 타임스탬프 (유닉스 타임)
https://api.example.com/items?start_date=1704067200

# 커스텀 형식 (예: YYYY-MM-DD)
https://api.example.com/items?start_date=2024-01-01

형식이 맞지 않으면 서버가 파라미터를 무시하거나 400 에러를 반환한다. API 문서를 확인하거나 서버 로그를 봐야 한다.

타임존 차이 이해하기

가장 흔한 문제는 타임존 미스매치다:

// 클라이언트 (로컬 타임존: 한국 UTC+9)
const date = new Date(2024, 0, 1); // 2024-01-01 00:00:00 KST
const iso = date.toISOString(); // 2024-01-01T15:00:00Z (UTC)

// 서버가 요청한 값을 UTC로 해석하면?
// start_date=2024-01-01T15:00:00Z는 한국 시간으로 2024-01-02 00:00:00이다!
// 따라서 2024-01-01 데이터를 못 가져온다.

해결 방법:

# UTC 자정 기준으로 요청
start_date=2024-01-01T00:00:00Z
end_date=2024-01-31T23:59:59Z

# 또는 타임스탬프 (UTC 기준)
start_date=1704067200  # 2024-01-01 00:00:00 UTC
end_date=1706745599    # 2024-01-31 23:59:59 UTC

경계값 처리 확인 (포함/제외)

API가 범위를 어떻게 처리하는지가 중요하다:

# start_date=2024-01-01&end_date=2024-01-02일 때
# 포함(inclusive): 2024-01-01 00:00:00 ~ 2024-01-02 23:59:59 사이의 모든 데이터
# 제외(exclusive): 2024-01-01 00:00:00 ~ 2024-01-02 00:00:00 사이의 데이터 (2024-01-02는 제외)

API 문서에 명시되지 않으면 테스트해봐야 한다:

# 경계에 정확히 하나의 데이터를 놓고 테스트
# 2024-01-01 00:00:00에 생성된 데이터를 기준으로

# 1. start_date=2024-01-01만 요청
curl 'https://api.example.com/items?start_date=2024-01-01'
# 그 데이터가 응답에 포함되는가?

# 2. end_date=2024-01-01만 요청
curl 'https://api.example.com/items?end_date=2024-01-01'
# 그 데이터가 응답에 포함되는가?

서버 타임존과 DB 저장 방식

서버가 데이터를 어떻게 저장하는지도 중요하다:

-- 데이터베이스의 created_at이 UTC 타임스탐프로 저장된 경우
SELECT * FROM items WHERE created_at >= '2024-01-01T00:00:00Z';

-- 반대로 로컬 타임존으로 저장된 경우는 필터링 로직이 다르다
SELECT * FROM items WHERE DATE(created_at) >= '2024-01-01';

이 차이를 모르면 로컬 테스트에서는 맞는데 운영에서 틀린 결과를 얻을 수 있다.

응답 데이터로 역검증한다

API 응답에 포함된 각 항목의 타임스탐프를 확인하자:

# 응답 예시
{
  "items": [
    { "id": 1, "created_at": "2024-01-01T08:30:00Z" },
    { "id": 2, "created_at": "2024-01-15T14:22:00Z" }
  ]
}

# 이 데이터들이 정말 2024-01-01~2024-01-31 범위에 들어가는가?
# 2024-01-01T08:30:00Z는 한국 시간으로 2024-01-01 17:30인가? (UTC+9)

필터 파라미터 생략 시 기본값 확인

start_date나 end_date를 생략하면 어떻게 되는가?

# start_date를 생략하면?
# -> 가장 오래된 데이터부터? 아니면 에러?

# end_date를 생략하면?
# -> 현재까지? 아니면 에러?

API 문서에 명시되지 않으면 한번 테스트해봐야 한다.

날짜 필터 문제는 로그와 응답을 자세히 보면 대부분 해결된다. 특히 타임존을 명시적으로 다루고, 경계값을 테스트하면 예측 불가능한 상황을 줄일 수 있다.