글 목록 API pagination 계약을 처음부터 정해야 하는 이유

문제 정의

글 목록은 단순해 보이지만 서비스가 커질수록 여러 화면에서 반복해서 쓰입니다. 홈 최신 글, 전체 글 목록, 카테고리 페이지, sitemap 생성, 관리자 글 목록이 모두 같은 API를 보거나 같은 정렬 기준을 기대합니다.

pagination 계약이 흐리면 사용자는 같은 블로그 안에서도 글 순서와 개수가 다르게 보이는 경험을 하게 됩니다.

상황과 배경

초기에는 posts 배열만 반환해도 충분합니다. 하지만 글 수가 늘면 total count, totalPages, page, limit, category filter, search query, sort 기준이 필요해집니다. sitemap 생성처럼 서버나 build script가 API를 읽는 경우에는 계약이 더 중요합니다.

URL query와 화면 상태를 맞추는 기준은 URL에 필터와 검색 상태를 남겨야 하는 이유에서 이어서 볼 수 있습니다.

pagination 계약의 핵심 필드

• items: 현재 페이지의 글 목록입니다.
• total: 필터가 적용된 전체 글 수입니다.
• page/limit: 현재 페이지와 요청 크기입니다.
• totalPages: UI가 마지막 페이지를 알 수 있게 합니다.
• sort: publishedAt, createdAt, popularity 등 정렬 기준을 명확히 합니다.

실제 적용 방법

블로그처럼 시간순 콘텐츠가 중요한 서비스는 기본 정렬을 publishedAt desc로 고정하는 편이 좋습니다. 임시 저장 글이나 예약 글이 섞이지 않도록 status 조건도 서버에서 강제합니다. 카테고리 count와 목록 필터는 같은 category slug source를 사용해야 합니다.

카테고리 count 불일치를 줄이는 운영 기준은 작은 블로그에 카테고리 구조가 필요한 이유와도 연결됩니다.

운영 체크리스트

• 홈, /posts, /categories/:slug가 같은 정렬 기준을 쓰는지 확인합니다.
• 필터 적용 후 total과 화면 카드 수가 자연스럽게 맞는지 확인합니다.
• limit 기본값과 최대값을 서버에서 제한합니다.
• sitemap 생성 스크립트가 모든 페이지를 순회할 수 있게 합니다.
• API 계약이 바뀌면 route shell과 관리자 화면도 함께 점검합니다.

결론

pagination은 UI 편의 기능이 아니라 콘텐츠 시스템의 데이터 계약입니다. 공개 라우트 계약과 함께 관리하면 검색엔진, 사용자, 운영자가 같은 글 목록을 보게 됩니다.