パイプライン設計の概要
Reddit Data APIは公式のライブデータではなく、独立した過去のアーカイブへのアクセスを提供します。GETによる取得ではAuthorization: Bearer YOUR_API_KEYまたはX-API-Key: YOUR_API_KEYを指定できます。どちらも有効ですが、例のプレースホルダーを実際のキーに置き換えるのは非公開の実行環境だけにしてください。キーと残高はこのドメイン専用です。
検索で使えるパラメータはq、subreddit、author、kind、from、to、min_score、limit、pageです。kindはpostまたはcommentです。fromとtoはUTCの暦日をYYYY-MM-DDで指定し、toの日も対象に含みます。これらは結果を絞る条件であり、完全な収集や統計的な代表性を保証しません。
上限は1リクエストあたり100レコード、1クエリあたり100ページです。ページを反復しても全件取得の保証はありません。受信した応答を保存してからローカルの進捗を更新してください。ページ番号は処理状況の記録であり、再開時の遠隔データが同じ順序であることや、欠落と重複がないことを保証するものではありません。
レスポンス構造とフィルタリング
取得されたデータはフラットなレコード形式で提供されます。親要素やリンクの関連フィールドが含まれる場合、クライアント側でグループ化できます。これはスレッドツリーをサーバーが構築することを意味するわけではなく、完全な祖先関係を保証するものではありません。クライアント側での処理が必要です。
min_scoreはスコアの降順ソートではなく、単なるフィルタリング条件として機能します。検索結果の順序は、アーカイブ内のドキュメント順序に基づいて返されます。これは時系列順でも関連度順でもスコア順でもありません。そのため、特定の並べ替えを期待している場合は、クライアント側で別途実装する必要があります。
GET /v1/postsとGET /v1/commentsではidを指定せず、既知の1件にはGET /v1/item?id=...を使います。GET /v1/subredditsはprefixとlimitでコミュニティ名を調べられますが、集計数が全体の厳密な件数とは限りません。応答にparent_idやlink_idがあっても、それらを検索パラメータとして使うことはできません。
エラーコードとページネーションの処理
HTTP 400は不正なリクエスト、401はキーの欠落または無効、402は残高不足、429はレート制限です。不正なリクエストは課金されず、取得元の失敗では予約したクレジットが返還されます。成功した空結果は1クレジットです。クライアントの通信断はサーバーの失敗と同義ではなく、その後の成功した再試行は別途課金されます。
ページネーションの総数は、eqなら正確な値、gteなら下限、unknownなら信頼できる総数が不明であることを示し、nullの場合もあります。下限を厳密な一致件数として扱わないでください。正確な総数が返っても、クライアントが全件を受信し保存した証明にはなりません。応答と関係値を一緒に保存し、ローカル処理の判断に使ってください。
GET /v1/statusはキー不要で無料です。静的な説明とHTTPサーバーの応答を示すだけで、検索の健全性や記録の存在を調べません。取込前には実際の取得結果の項目と型を検証してください。予期しないレコードを黙って変換せず、除外理由や変換版をローカルに残せば、保存済み応答に対する処理を検証できます。
