API 목록을 페이지와 커서로 빠짐없이 이어 읽는 법

API는 프로그램이 다른 서비스에 자료나 기능을 요청하는 약속입니다. 상품, 결제, 댓글처럼 목록이 길어지면 서버는 결과를 한 번에 전부 보내지 않고 작은 묶음으로 나눠 줄 수 있습니다. 첫 응답에 열 개만 보인다고 해서 자료가 열 개뿐이라는 뜻은 아닙니다.

긴 서류 더미를 얕은 상자 여러 개에 나눠 담는 모습을 떠올려 보세요. 한 상자를 다 읽은 뒤에는 “다음 상자는 여기부터”라고 표시된 책갈피를 이어 받아야 합니다. 페이지네이션은 긴 목록을 여러 상자로 나누는 방식이고, 커서는 다음에 읽을 위치를 가리키는 책갈피입니다.

페이지네이션은 긴 목록을 작은 응답으로 나눈다

페이지네이션은 많은 목록을 여러 응답으로 나눠 전달하는 방식입니다. GitHub 공식 문서는 결과가 많을 때 전체 중 일부를 반환하고, 응답의 link 헤더로 다음 페이지를 요청할 수 있다고 설명합니다. Google의 API 설계 지침도 목록은 계속 커질 수 있어 응답 크기와 조회 시간을 관리하려면 처음부터 페이지를 나누는 설계가 중요하다고 안내합니다.

따라서 목록 API를 처음 볼 때는 배열 길이만 세지 말고 다음 결과가 있다는 신호를 함께 찾습니다. 서비스에 따라 Link 헤더의 rel="next", 응답 본문의 next_page_token, has_more, next_cursor처럼 모양과 이름이 다릅니다. 사용 중인 API 문서가 정한 필드와 종료 조건을 먼저 확인해야 합니다.

페이지 번호와 커서는 다음 위치를 표현하는 두 방식이다

페이지 번호 방식은 page=1, page=2처럼 묶음의 순서를 숫자로 요청합니다. 화면에서 첫째 장, 둘째 장을 넘기는 모습과 가까워 이해하기 쉽습니다. 다만 API마다 페이지 크기와 마지막 페이지를 표현하는 규칙이 다르므로 숫자를 임의로 늘리기보다 응답이 제공한 다음 링크를 따르는 편이 안전합니다.

커서는 서버가 다음에 이어 읽을 위치를 나타내도록 건네는 값입니다. Stripe의 목록 API는 기존 객체의 식별자를 starting_after에 넣어 다음 묶음을 요청합니다. Google 지침의 page_token도 앞선 응답에서 받은 값을 다음 요청에 전달하도록 설계됩니다. 커서의 생김새를 해석해 직접 새 값을 만들지 말고 받은 값을 그대로 사용합니다.

서버가 준 다음 신호를 그대로 따라간다

다음 응답을 가져오는 코드는 서비스마다 다르지만 흐름은 비슷합니다. 아래는 실제 비밀키나 운영 주소 없이 구조만 보여 주는 예시입니다.

{
  "data": [
    { "id": "item_a" },
    { "id": "item_b" }
  ],
  "next_cursor": "opaque-value",
  "has_more": true
}

이 응답은 자료가 두 개뿐이라는 뜻이 아니라, 지금 묶음에 두 개가 있고 다음 묶음이 남았다는 뜻입니다. 다음 요청에는 문서가 정한 위치에 opaque-value를 넣습니다. opaque는 안쪽 의미를 사용자가 해석하지 말아야 한다는 뜻입니다. Google 지침은 페이지 토큰을 사용자가 분해할 수 없는 값으로 다루고, 토큰 자체를 자료 접근 권한으로 사용하지 말라고 명시합니다.

필터와 정렬 조건은 다음 요청에서도 유지한다

첫 요청에서 날짜 범위, 상태, 정렬 방향을 정했다면 다음 페이지에서도 같은 조건을 유지해야 합니다. Google 지침은 페이지 토큰을 받은 뒤 이어 요청할 때 토큰과 페이지 크기를 제외한 다른 인수를 앞선 호출과 같게 유지하도록 안내합니다. 중간에 조건을 바꾸면 같은 책갈피를 다른 서류 더미에 꽂는 것과 비슷해집니다.

수집을 시작할 때 다음 항목을 한 줄로 묶어 기록해 두면 비교하기 쉽습니다.

• 요청 주소와 목록 종류를 기록합니다.
• 날짜 범위와 상태 필터를 기록합니다.
• 오래된 순인지 최신 순인지 정렬 방향을 기록합니다.
• 한 페이지에서 요청한 최대 개수를 기록합니다.
• 응답에서 다음 위치를 알려 주는 필드를 기록합니다.
• 마지막 페이지를 판단하는 신호를 기록합니다.

서버는 요청한 페이지 크기보다 적은 항목을 돌려줄 수 있습니다. Google 지침도 끝에 도달하지 않았어도 요청한 수보다 적거나 빈 결과를 반환할 수 있다고 설명합니다. 따라서 “열 개를 요청했는데 여덟 개가 왔다”만으로 끝이라고 단정하지 말고 공식 종료 신호를 확인합니다.

목록이 바뀌는 동안에는 빠짐과 중복을 따로 점검한다

페이지를 읽는 사이 새 항목이 생기거나 기존 항목의 순서가 바뀔 수 있습니다. 커서는 이어 갈 위치를 알려 주지만 모든 API가 시작 순간의 목록을 그대로 얼려 보관한다고 보장하지는 않습니다. 페이지 번호든 커서든 사용하는 서비스의 정렬 기준과 일관성 보장을 문서에서 확인해야 합니다.

수집한 각 항목의 고유 식별자, 예를 들면 id를 함께 저장하면 같은 항목이 다시 왔는지 알아볼 수 있습니다. 중복 식별자는 무조건 지우기 전에 왜 반복됐는지 기록하고, 예상한 기간의 첫 항목과 마지막 항목이 포함됐는지도 확인합니다. 전체 개수 필드가 있더라도 추정치일 수 있으므로 그것만으로 완전성을 단정하지 않습니다.

종료와 재시도 조건을 먼저 정한다

GitHub는 다음 페이지가 있을 때 Link 헤더에 rel="next"를 제공하고, Stripe는 has_more가 거짓이면 목록의 끝이라고 설명합니다. Google 지침에서는 next_page_token이 비어 있으면 끝입니다. 종료 조건이 서로 다르므로 “빈 배열이 나오면 무조건 끝” 같은 한 규칙을 모든 API에 적용하지 않습니다.

오류가 나면 같은 요청을 빠르게 무한 반복하지 않습니다. 응답 상태와 재시도 안내, 현재 커서, 이미 저장한 마지막 식별자를 기록하고 API의 호출 제한 문서를 확인합니다. 재시작할 때는 마지막으로 성공한 페이지와 저장 완료 지점을 구분해야 같은 자료를 두 번 반영하거나 중간 묶음을 건너뛰지 않습니다.

비밀키와 결제와 삭제 목록에는 더 좁은 경계를 둔다

API 키와 접근 토큰은 요청 예시, 브라우저 화면, 로그, 공개 저장소에 넣지 않습니다. 커서는 다음 위치일 뿐 권한 증명이 아니므로 서버는 각 요청의 인증과 권한을 별도로 확인해야 합니다. 커서 값에도 내부 정보가 포함될 수 있다고 보고 공개 글이나 오류 화면에 그대로 노출하지 않습니다.

결제, 환불, 사용자 삭제 목록은 읽기 수집과 실제 변경 작업을 분리합니다. 목록을 모두 읽었다는 이유로 각 항목에 취소나 삭제 요청을 자동 실행하지 마세요. 시험 계정과 읽기 전용 권한부터 사용하고, 예상 개수 상한과 중단 조건, 사람의 최종 확인을 둡니다. 모르는 SDK 설치 명령이나 운영 데이터 변경 명령도 실행하지 않습니다.

오늘 바로 해볼 작은 실습

실제 API를 호출하거나 비밀키를 입력하지 않고 10분 동안 공개 문서의 페이지 흐름만 그려 봅니다.

1. 사용하는 서비스의 목록 API 문서 한 곳을 엽니다.
2. 첫 응답에서 자료 배열의 필드 이름을 찾습니다.
3. 다음 링크나 커서 필드의 이름을 적습니다.
4. 페이지 크기를 정하는 필드와 최대값을 확인합니다.
5. 날짜, 상태, 정렬처럼 계속 유지할 조건을 적습니다.
6. 끝을 알리는 공식 신호를 한 문장으로 씁니다.
7. 항목을 중복 확인할 고유 식별자를 찾습니다.
8. 오류가 날 때 기록할 상태 코드와 현재 커서를 적습니다.
9. 예시에 비밀키, 실제 결제, 개인정보가 없는지 확인합니다.
10. 삭제나 환불처럼 자료를 바꾸는 호출은 실행하지 않습니다.

마지막으로 “첫 묶음의 항목 수, 다음 위치, 종료 신호”를 서로 다른 세 칸에 적어 보세요. 세 값을 구분할 수 있으면 첫 화면만 전체라고 오해하지 않고, 긴 API 목록을 어디까지 읽었는지 차분하게 확인할 수 있습니다.