API 페이지네이션: 페이지 경계와 완전성 추적
작성: Ai Flowi · 게시일
API 페이지네이션은 컬렉션을 여러 개의 작은 응답으로 나누고 호출자가 다음 부분을 요청하는 방식을 정의합니다. 결과를 수집하려면 각 페이지 경계를 보존하고, 계약에 명시된 후속 요청 규칙을 따르며, 명시적인 종료 조건을 확인해야 합니다. 첫 응답이 성공했다는 것은 해당 페이지의 결과만 확인해 줄 뿐, 전체 컬렉션을 가져왔다는 뜻은 아닙니다.
완전성을 판단하는 범위에는 선택한 필터, 정렬 순서, 권한, 컬렉션 버전이 포함됩니다. 호출자가 접근할 수 없는 레코드를 제외한 채 페이지 순회가 정상적으로 끝날 수도 있습니다. 순회 중 컬렉션이 바뀐다면, 중단 없이 이어진 페이지라도 하나의 일관된 스냅샷을 나타내지 못할 수 있습니다.
오프셋 방식과 커서 방식의 페이지네이션은 어떻게 다른가요?
오프셋 방식은 정렬된 결과 내의 위치를 요청하며, 보통 페이지 크기도 함께 지정합니다. 커서 방식은 서비스가 제공한 값으로 표시되는 후속 위치를 요청합니다. 두 방식 모두 순서, 종료 조건, 원본 레코드가 바뀔 때의 동작을 설명하는 계약이 필요합니다.
| 방식 | 호출자가 보존할 정보 | 주요 불확실성 |
|---|---|---|
| 오프셋 | 요청한 위치, 크기, 필터, 정렬 순서 | 해당 위치 앞에서 레코드가 추가되거나 삭제되면 이후 레코드의 위치가 달라질 수 있습니다. |
| 커서 | 반환된 후속 요청 값과 그에 연결된 쿼리 | 커서만으로는 고정된 스냅샷, 무기한 유효성, 전체 개수를 보장할 수 없습니다. |
내부 의미를 알 수 없는 커서는 지정된 방식대로 다시 전달할 데이터로 취급하세요. API가 허용하지 않는 한 값을 증가시키거나 행 번호로 해석하거나 다른 필터에 재사용하지 마세요. 항목이 적은 페이지나 빈 페이지는 제공된 계약에서 그렇게 정의한 경우에만 종료 신호입니다.
이 예제를 위해 작성한 3페이지 응답 계약
이 가상의 읽기 API는 예제용 항목 ID 6개를 고정된 순서로 제공합니다. 이 학습용 테스트 데이터에 한해서만 컬렉션은 변경되지 않으며, 마지막 페이지를 제외한 각 페이지에는 항목 2개가 있고 예상 ID도 알려져 있습니다. next_cursor 필드에는 다음 요청에 사용할 값이 들어 있으며, JSON의 null은 순회를 명시적으로 종료합니다. 이 필드가 없으면 잘못된 응답이며, 종료 신호를 대신하지 않습니다.
{"items":[{"id":"item-A"},{"id":"item-B"}],"next_cursor":"page-two"}
{"items":[{"id":"item-C"},{"id":"item-D"}],"next_cursor":"page-three"}
{"items":[{"id":"item-E"},{"id":"item-F"}],"next_cursor":null}세 객체는 작성된 예제 본문이며 실제 운영 응답이 아닙니다. 최초 요청에는 커서를 넣지 않고, 이후 요청에는 직전 next_cursor 값을 그대로 전달합니다. 단어처럼 보이는 커서 값은 예제를 읽기 쉽게 하려는 것이며, 실제 서비스는 사람이 읽어도 의미를 알 수 없는 값을 제공할 수 있습니다.
| 페이지 | 요청 커서 | 관찰된 ID | 반환된 next_cursor | 기록부 판단 |
|---|---|---|---|---|
| 1 | 없음: 최초 요청 | item-A, item-B | page-two | 페이지를 저장하고 page-two를 요청합니다. |
| 2 | page-two | item-C, item-D | page-three | 페이지를 저장하고 page-three를 요청합니다. |
| 3 | page-three | item-E, item-F | null | 종료 표시를 확인하고 ID 6개 모두를 테스트 데이터와 비교합니다. |
각 행에 시도 식별자, 응답 판정, 관찰 시각을 함께 기록하세요. 요청 커서는 페이지 경계를 식별하며, 별도의 시도 식별자는 같은 경계에서의 재시도를 구분합니다. 민감한 후속 요청 값은 공개 로그가 아닌 접근이 제한된 증빙에 저장하세요.
반복 커서, 중복 ID, 누락 페이지 감지
| 실패 유형 | 변경된 관찰 결과 | 기록부가 감지하는 문제 | 처리 방침 |
|---|---|---|---|
| 커서 반복 | 2페이지에서 page-two가 다시 반환됩니다. | 후속 요청이 이미 수락한 경계를 다시 요구합니다. | 순회를 중단하고 진행이 없음을 표시합니다. |
| ID 중복 | 2페이지에 item-B와 item-D가 들어 있습니다. | item-B는 1페이지에 있었고 item-C는 없습니다. | 두 페이지의 관찰 기록을 모두 보존하고 고유 ID 테스트를 실패로 판정합니다. |
| 페이지 누락 | 호출자가 1페이지에서 곧바로 page-three로 이동합니다. | 다음 요청이 1페이지에서 받은 후속 값 page-two와 일치하지 않습니다. | 마지막 페이지가 null을 반환해도 컬렉션을 부분 수집으로 표시합니다. |
중복 ID를 조용히 제거하면 유용한 증빙이 가려집니다. 허용된 중복 제거를 수행하기 전에 원래의 출현 횟수와 각 항목이 나온 페이지를 보존하세요. 변경되지 않는 이 예제에서 중복은 계약 위반입니다. 변경되는 컬렉션에서는 경계 사이로 항목이 이동했음을 드러낼 수도 있습니다. 어느 경우든 중복 제거만으로 누락된 레코드를 복구할 수는 없습니다.
알려진 ID 6개의 테스트 데이터는 독립적인 완전성 검사를 제공합니다. 예상 목록이 없는 실제 호출자는 고유 ID의 개수를 세는 것만으로 모든 원본 레코드가 반환되었다고 입증할 수 없습니다. 관찰한 순서가 제공된 계약을 따랐다는 점을 확인한 뒤, 원본의 완전성이나 스냅샷 일관성에 관한 한계를 명시할 수 있습니다.
수집 전에 ‘완전함’의 의미 정의하기
필요한 모든 응답이 합의된 본문 검사를 통과하고, 각 후속 요청을 따랐으며, 문서에 명시된 종료 조건에 도달한 뒤에만 컬렉션을 수락하세요. 원래 쿼리와 제공된 스냅샷 참조는 고정해 두세요. ‘순회 종료’와 ‘독립적인 원본과 목록 대조 완료’를 구분하세요.
요청 횟수 상한이나 마감 시간은 무한 순회로부터 호출자를 보호하지만, 상한에 도달했다고 정상 종료한 것은 아닙니다. 부분 결과와 미해결인 다음 경계를 기록하세요. 커서가 만료되면 서비스의 재시작 규칙을 따르세요. 재시작한 순서를 이전 페이지에 붙이고 그 혼합 결과를 하나의 스냅샷이라고 부르지 마세요.
응답이 실패하면 마지막으로 수락한 페이지와 실패한 시도를 분리해 보관하세요. 본문을 검증하기 전에 레코드를 추가하면 잘못된 페이지가 컬렉션에 섞일 수 있습니다. 복구 시에는 쿼리의 동일성과 마지막으로 검증한 경계를 모두 보존해야 합니다.
AI Flowi Workflow 요청의 페이지네이션
상태: 문서화됨. 컴포넌트의 요청 필드는 API Request 문서를 참조하세요. 해당 필드는 카탈로그에 문서화되어 있으나 Ai Flowi가 실제 운영 환경에서 테스트하지 않았습니다
.
예제 설정이며, 기록된 테스트가 아닙니다
가상의 요청 매핑에서는 쿼리 매개변수 이름을 cursor로 정하고 query_params에 넣습니다. 처음에는 생략하고, 앞선 본문을 검증한 뒤에만 page-two와 page-three를 전달합니다. 이 값은 테스트 데이터이며 카탈로그 옵션이 아닙니다. 응답 필드 next_cursor와 요청 매개변수 cursor의 이름은 의도적으로 다릅니다. 응답 키를 요청 키로 그대로 복사하면 이 가상 엔드포인트의 계약을 위반합니다.
2페이지를 수락한 뒤에는 다음 요청이 page-three이고 저장된 ID는 item-A부터 item-D까지입니다. 다음 시도가 사용 가능한 본문을 반환하기 전에 실패하면 ID 4개를 부분 컬렉션으로 유지하고 page-three는 미해결로 보존하세요. 요청을 보냈다는 이유만으로 기록부를 다음 단계로 넘기지 마세요. 이후 재시도에서 유효한 마지막 본문을 받으면 item-E와 item-F를 한 번만 수락하고 ID 6개의 목록을 대조하세요. 이는 테스트 데이터를 수동으로 검토하는 과정이며, 기본 제공 자동 페이지네이션 기능을 주장하는 것이 아닙니다.
AI Flowi Workflow 계정을 사용하고, API에 필요한 계정이나 자격 증명은 제공업체에서 확보하세요. 외부 사용료는 별도로 청구됩니다. 위의 페이지 본문 예제는 해당 컴포넌트를 통해 가져온 것이 아닙니다.
흔한 실수와 관련 용어
- 첫 번째 200 응답을 완전한 내보내기 결과로 저장하는 것.
- 유효한 후속 요청 값이 있는데도 items 목록이 비었다는 이유로 종료하는 것.
- 새 컬렉션 기록을 시작하지 않고 순회 도중 필터를 바꾸는 것.
- 페이지 연속성을 확인하기 전에 중복 출현 기록을 지우는 것.
- 일관성 보장이 제공되지 않았는데도 커서 기반 컬렉션을 스냅샷이라고 부르는 것.
종료 조건, 가시성 범위, 일관성 요구사항이 미해결인 수집 목록은 대조 작업에 사용하지 마세요. 더 넓은 인터페이스 계약은 API 연동, 응답 검증은 API 테스트, 연속 요청이 소모하는 허용량은 API 호출 제한, 각 페이지 응답의 의미는 HTTP 상태 코드를 참조하세요.