API 페이지네이션 응답 형식을 바꿀 때 주의할 것

API 페이지네이션은 단순해 보이지만, 클라이언트마다 기대하는 형식이 다를 수 있다. 응답 형식을 바꾸면 일부 클라이언트는 목록을 받지 못할 수 있다.

현재 페이지네이션 형식 파악

보통 페이지네이션 응답은 다음 정보를 포함한다:

• page: 현재 페이지 번호
• limit: 페이지당 항목 수
• total: 전체 항목 수
• items: 실제 데이터

하지만 구현마다 다를 수 있다. 어떤 곳은 offset/limit 방식을 쓰고, 어떤 곳은 cursor 방식을 쓴다.

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

실제 응답을 받아서 필드를 정확히 파악한다.

요청 파라미터도 함께 확인

API를 호출하는 방식도 중요하다. 클라이언트가 ?page=1&limit=10 형식을 기대하는데, 응답을 offset/count 방식으로 바꾸면 곤란하다.

현재 사용 중인 모든 요청 형식을 수집해서, 변경 후에도 호환되는지 확인하자.

응답 형식 변경은 새 버전으로

기존 응답 형식을 버리고 새 형식으로 완전히 바꾸려면, 새로운 API 버전을 만드는 게 낫다.

• /api/v1/items: 기존 페이지네이션 (계속 지원)
• /api/v2/items: 새로운 페이지네이션 형식

이렇게 하면 기존 클라이언트는 영향받지 않고, 새로운 클라이언트는 새 형식을 쓸 수 있다.

상태 코드와 에러 메시지도 일관성 있게

페이지 번호가 범위를 벗어났을 때(예: page=999), 어떻게 응답할지를 정해야 한다.

• 빈 배열을 반환할 것인가?
• 404 Not Found를 반환할 것인가?
• 400 Bad Request를 반환할 것인가?

클라이언트 입장에서는 일관성 있는 응답이 중요하다.

브라우저에서도 테스트

API를 직접 호출하는 것뿐 아니라, 실제 웹 앱이나 모바일 앱에서 목록이 제대로 로드되는지 테스트해야 한다.

특히 다음을 확인하자:

• 첫 페이지가 로드되는가?
• 다음 페이지로 이동할 수 있는가?
• 마지막 페이지 판단이 올바른가?
• 에러 상황 처리가 적절한가?

변경 후에도 모니터링

배포한 후 클라이언트 에러율을 주시한다. 페이지네이션 오류는 보통 "목록이 안 보인다"거나 "끝없이 로드한다"는 리포트로 들어온다.

문제가 보이면 빠르게 롤백할 수 있도록 준비해두자.