시계열 데이터 조회 API 설계: 기간, 컬럼, 대상 옵션 정리

시계열 API는 사용자가 가장 많이 만지는 입구다. 그래서 자유롭게 보이게 만들고 싶지만, 기간과 대상과 컬럼을 모두 열어두면 한 번의 요청이 배치 작업처럼 커질 수 있다. 좋은 API는 편한 요청과 안전한 제한을 같이 갖고 있다.

시계열 데이터 조회 API 설계: 기간, 컬럼, 대상 옵션 정리 핵심 구조도

요청 옵션을 세 덩어리로 나눈다

옵션	예시	제한 기준
대상	ticker, security_id, universe	entity_count
기간	start, end, lookback	range_days
컬럼	close, volume, factor	column_count
응답 형태	wide, long, paged	payload_size

요청 비용을 숫자로 계산한다

query_weight = entity_count * range_days * column_count

if query_weight > 2_000_000:
    return 413, 'request too large; narrow entities, dates, or columns'

사용자에게 친절한 제한

그냥 실패시키지 말고 어떤 축을 줄이면 되는지 알려준다. 예를 들어 기간을 3년으로 줄이거나 컬럼을 close, volume만 선택하라고 안내한다.

응답 설계 팁

• 기본 컬럼을 작게 두고 필요한 컬럼만 명시하게 한다.
• 긴 기간 요청은 페이지 단위로 나눠 내려준다.
• 캐시 키에는 대상, 기간, 컬럼, 조정 기준을 모두 넣는다.

실전 적용 포인트

시계열 API는 자유도가 높을수록 사용하기 좋아 보이지만, 제한이 없으면 한 번의 요청이 배치 작업만큼 커질 수 있다. 기간, 대상 수, 컬럼 수를 함께 제한해야 응답 속도와 서버 비용을 예측할 수 있다.

좋은 API는 실패할 때도 다음 행동을 알려준다. 단순히 요청이 크다고 막기보다 기간을 줄이거나 컬럼을 줄이라는 메시지를 주면 사용자는 같은 오류를 반복하지 않는다.

• 요청 비용을 entity_count, range_days, column_count로 계산한다.
• 큰 조회는 페이지 단위로 나누어 반환한다.
• 오류 메시지에는 줄여야 할 축을 구체적으로 적는다.

함께 보면 좋은 글

• 주기성 재무 데이터 API 설계
• 분산 조인 성능 비교