API

API pagination 응답에 totalCount를 함께 보내야 하는 이유

totalCount 없이는 클라이언트가 페이지 수를 계산할 수 없다. 그리고 마지막 페이지인지도 알 수 없어서 무한 스크롤 구현이 복잡해진다.

2026년 6월 22일·1분 읽기

API에서 pagination을 구현할 때 items 배열만 반환하면 클라이언트가 페이지 수를 못 본다.

최소한의 pagination 응답

{
  "items": [...],
  "totalCount": 250,
  "page": 1,
  "pageSize": 20
}

이 정보들로 클라이언트는 "총 250개 중 20개씩 보고 있다"는 걸 알 수 있다.

const totalPages = Math.ceil(totalCount / pageSize);
const isLastPage = page === totalPages;
const hasNextPage = page < totalPages;

totalCount가 없으면 이 계산들을 할 수 없다. 그래서 무한 스크롤을 구현할 때 "응답이 pageSize보다 적으면 마지막 페이지"라는 휴리스틱에 의존해야 하는데, 이건 불안정하다.

curl -i 'https://example.com/api/items?page=1&pageSize=20'

# 응답
{
  "items": [...20개...],
  "totalCount": 1250,
  "page": 1,
  "pageSize": 20
}

이렇게 하면 프론트엔드에서 "1250개 중 20개씩 페이지네이션하기"를 완벽하게 구현할 수 있다.