利用者の問いをパラメーターにする
最初に、アプリが答える問いを決めます。特定コミュニティの製品議論を探す場合と、ある投稿者のコメントを調べる場合では必要な条件が違います。検索語をq、コミュニティをsubreddit、投稿者をauthorに渡し、有効な条件を結果の近くに表示してください。未対応の独自検索構文を使えるように見せないことも重要です。
日付選択の結果はUTCを基準にYYYY-MM-DDへ変換します。fromが開始、toが指定日を含む終了日です。画面で地域別の日付を表示する場合も、APIへ送る実際の範囲が分かるようにします。投稿だけならkind=post、コメントだけならkind=commentです。min_scoreは最低スコアであり、人気順の要求ではありません。
検索フォームには、独立した過去のアーカイブを利用していることを添えます。ライブ更新、Redditとの公式な関係、完全な履歴検索を約束しないでください。狭い条件でもすべての関連記録が返るとは限りません。調べたい対象と実際に取得したサンプルを区別すれば、利用者が結果を過度に一般化することを避けやすくなります。
取得範囲と画面の表示を合わせる
GET /v1/search、または用途に応じて/v1/postsと/v1/commentsを使い、X-API-Keyヘッダーで認証します。limitとpageは1～100です。各呼び出しで最大100件の1ページを取得し、次ページは別に要求します。利用者が必要とする範囲に合わせ、全ページを自動で取りに行くかどうかを設計してください。
結果は内部の_doc順で、時系列順でも関連度順でもありません。ローカルで日付順に並べるなら、取得済みデータ内の並べ替えと明示します。各レコードのフィールドの有無を調べて表示し、同一の項目が必ずそろうと仮定しないでください。parent_idやlink_idがあれば関連付けられますが、完全な会話ツリーではない可能性があります。
eqは正確なクエリ一致件数、gteは少なくともその件数、unknownは総数不明として表示します。下限の値を最終ページの証拠にしないでください。100ページまで繰り返しても全件取得を保証しません。複数の条件に分割する場合も、重複や欠落がないと断定せず、ローカル処理と取得範囲の記録でその限界を扱います。
エラー処理と分析の根拠を残す
400ではパラメーター、401ではキーとヘッダー、402では残高を確認します。429には待機付きの再試行を使い、繰り返し回数に上限を設けます。/v1/statusは静的な説明とHTTP応答の確認に限られ、検索基盤やデータの準備状態は検査しません。接続できることと、目的の検索が成功することを同じ指標にしないでください。
成功した呼び出しは空でも1クレジットです。上流の失敗は予約分を返しますが、クライアント切断がサーバーの成功後なら課金されている可能性があります。成功した再試行も有料です。生の応答、検索条件、ローカル変換のコードを一緒に保存すれば、後のAPI応答が変わっても、その分析に使ったデータと手順を説明できます。
