다음 행동의 범위를 작게 유지하세요
설명용 하이킹 앱이 hiking에서 offline maps를 limit=3, page=1로 요청했다고 가정합니다. 독자는 반환된 참고 자료를 열고 다음 묶음도 도움이 될지 판단합니다. 더 보기는 같은 질문에 대한 다음 페이지를 요청해야 합니다. 모든 페이지의 수집을 조용히 시작하거나, 예전 결과를 보여 주면서 쿼리를 바꾸어서는 안 됩니다.
응답이 다음 페이지를 허용할 때 더 보기 버튼을 표시해 사용자가 알아볼 수 있게 합니다. 그 동작의 응답을 기다리는 동안 반복 실행을 막고, 이미 표시된 참조 자료는 유지하세요. 정상적인 페이지 요청은 빈 페이지라도 1크레딧을 사용합니다. 다음 페이지를 요청하기 전에 멈추면 그 향후 요청을 피하지만, 화면을 떠난다고 이미 전송한 요청이 취소되거나 크레딧이 반환되지는 않습니다.
요청 상태를 함께 유지하세요
page가 증가할 때 q, subreddit, 선택한 다른 필터, limit을 그대로 유지하세요. 문구나 날짜 범위가 바뀌면 page=1에서 새 결과 순서를 시작합니다. 다른 질문의 두 번째 페이지를 예전 목록에 섞으면 두 요청 모두 성공해도 읽기 이력이 오해를 일으킵니다.
아카이브는 _doc 순서를 사용합니다. 시간순, 관련도순, 점수순이 아니며, min_score는 정렬 명령이 아니라 필터입니다. 화면에 보여 주려고 이미 가져온 레코드를 재정렬할 수 있지만 전체에서 최신이거나 최선인 일치를 찾았다는 뜻은 아닙니다. 반복 페이지 요청에 고정 스냅샷이 보장되지는 않습니다.
빈 페이지가 나올 때까지 추측하지 말고 응답을 사용하세요
pagination.has_more는 요청 범위에서 가능한 경우 추가로 미리 읽은 레코드를 기준으로 합니다. has_more가 true이고 페이지가 100 미만일 때만 다음 동작을 제공하세요. 빈 페이지가 나타날 때까지 계속 조회하지 마세요. 서비스가 이미 계속 진행할 신호를 제공하며, 추가 정상 요청은 크레딧을 사용합니다.
pagination.total은 pagination.relation과 함께 읽습니다. eq는 해당 응답의 집계 의미에서 정확한 수이고, gte는 통계적 추정치가 아닌 하한이며, unknown은 신뢰할 총수가 없다는 뜻으로 null과 함께 올 수 있습니다. 가상의 첫 응답이 레코드 세 개, total 4, relation gte를 보여 준다면 「최소 네 개의 일치가 표시됩니다」라고 안내할 수 있습니다. 정확히 네 개라고 말해서는 안 됩니다.
조회 범위의 상한을 인식하세요
한도는 요청당 100레코드, 100페이지입니다. limit=100인 100페이지가 가득 차면 추가 선행 조회 레코드를 가져올 여유가 없습니다. 따라서 pagination.window_exhausted는 true, has_more는 false, relation은 gte일 수 있습니다. 이 경계에서 has_more가 false라고 해서 아카이브에 더 이상의 일치가 없다는 증거는 아닙니다.
첫 페이지 이후의 빈 페이지 역시 전체 총수를 확정하지 못하며, 게이트웨이는 이 경우 총수를 알 수 없음으로 표시합니다. 「모든 토론을 불러왔습니다」 대신 「이 검색의 조회 범위에 도달했습니다」처럼 실제 한계를 설명하세요. 쿼리를 좁히면 추가 작업을 정리할 수 있지만, 제한된 요청이 전체 내보내기로 바뀌지는 않습니다.
조심스럽게 합치고 실패에서 복구할 수 있게 하세요
실제 레코드 식별자가 있으면 앱이 누적한 목록에서 같은 레코드를 두 번 표시하지 않도록 사용할 수 있습니다. 실제로 받은 필드로 식별 규칙을 정하세요. 없는 ID를 만들거나, 텍스트가 비슷하다는 이유만으로 서로 다른 레코드를 합치지 마세요. 로컬 중복 제거는 남은 목록의 완전성을 입증하지 않습니다.
다음 페이지 요청이 실패해도 이전 레코드와 쿼리를 그대로 두고 명시적 재시도 선택을 제공하세요. 결과를 알 때까지 대기 중인 페이지 번호를 별도로 유지하고, 순서가 뒤바뀐 응답은 자체 앱 로직으로 처리합니다. API는 커서 엔드포인트를 제공하거나 이 UI 상태를 대신 관리하지 않습니다. 별도의 로딩 상태와 요청 예산 예시는 /ko/#field-notes에서 확인하세요.
