次の操作を小さく保つ
説明用のハイキングアプリが、hikingでoffline mapsをlimit=3、page=1として要求したとします。読み手は返された参照資料を開き、もう一組読むと役立つかを判断します。「さらに表示」は、同じ疑問の次ページを要求する操作にします。すべてのページの収集をひそかに始めたり、古い結果を残したままクエリを変えたりしてはいけません。
レスポンスが次ページを許すときに「さらに表示」を出し、利用者に分かる手掛かりにします。その操作の応答待ち中は重複実行を防ぎ、表示済みの参照資料は残してください。各ページの正常な取得には、空のページでも1クレジットがかかります。次ページを要求せずにやめれば、その先のリクエストを避けられます。ただし画面を離れても、すでに送信したリクエストの取消しや返還は保証されません。
リクエストの状態をひとまとめに保つ
pageを増やすときはq、subreddit、その他のフィルター、limitを変えません。語句や日付範囲を変更したら、page=1から新しい結果列を始めます。別の疑問の2ページ目を古い一覧に混ぜると、両方のリクエストが成功しても、閲覧の履歴が誤解を招きます。
アーカイブは_doc順を使います。時系列、関連度、スコアの順ではなく、min_scoreは並べ替えではなくフィルターです。表示のために取得済みレコードを並べ替えることはできますが、全体で最新または最良の一致が分かるわけではありません。ページを繰り返し取得しても、固定スナップショットの保証はありません。
空になるまで試さず、レスポンスを読む
pagination.has_moreは、取得範囲に余地がある場合の先読みレコードに基づきます。has_moreがtrueで、ページが100未満のときだけ次の操作を示してください。空のページが出るまで取得し続ける必要はありません。サービスは続きを判断する値を返しており、余分な正常リクエストにはクレジットがかかります。
pagination.totalはpagination.relationと併せて読みます。eqはそのレスポンスの集計定義での確定値、gteは統計的な推計ではなく下限値、unknownは信頼できる総数がないことを意味し、nullを伴う場合があります。仮に最初のレスポンスで3レコードが表示され、totalが4、relationがgteなら、「少なくとも4件の一致が示されています」と案内できます。「正確に4件ある」とは言えません。
上限のある取得範囲を理解する
上限は1リクエスト100レコード、100ページです。limit=100で100ページ目が満杯の場合、追加の先読みレコードを取る余地がありません。そのため、pagination.window_exhaustedがtrueでも、has_moreはfalse、relationはgteになり得ます。この境界でhas_moreがfalseでも、アーカイブにこれ以上の一致がない証拠にはなりません。
2ページ目以降の空のページでも、全体の総数は確定できません。その場合ゲートウェイは総数を不明とします。「すべての議論を読み込みました」ではなく、「この検索の取得範囲に達しました」など、実際の境界を説明してください。クエリを絞れば次の作業を整理できますが、範囲を限ったリクエストが完全なエクスポートに変わるわけではありません。
慎重に結合し、失敗から戻れるようにする
実際のレコード識別子がある場合、アプリが蓄積する一覧で同じレコードを二重に表示しないために使えます。識別規則は取得したフィールドに基づいて決め、欠けたIDを作ったり、本文が似ているだけで別のレコードを統合したりしないでください。ローカルで重複を除いても、残った一覧の完全性は証明できません。
次ページの取得に失敗したら、以前のレコードとクエリを残し、明示的な再試行操作を示します。結果が分かるまでは要求中のページ番号を別に管理し、順序が前後したレスポンスはアプリ自身のロジックで扱ってください。APIはカーソル用エンドポイントを提供せず、このUI状態も管理しません。独立した読み込み状態とリクエスト予算の例は/ja/#field-notesを参照してください。
