経路と認証の境界
取得先はhttps://api.redditapigateway.comです。GETの/v1/searchは検索、/v1/postsは投稿、/v1/commentsはコメントの取得に使用します。個別識別子が分かる場合は/v1/item?id=...、コミュニティ名を接頭辞で探す場合は/v1/subreddits?prefix=...を使います。/v1/statusは公開の状態経路です。これらは独立した過去のアーカイブ用であり、公式Reddit APIの全経路をそのまま中継するものではありません。
取得認証ではAuthorization: Bearer YOUR_API_KEYとX-API-Key: YOUR_API_KEYの両方を受け付けます。値にはこのドメインで発行したアーカイブキーを使い、Reddit OAuthトークンを入れないでください。実値は実行環境で読み込み、公開コードに残さないようにします。アカウントパネルは別のSecure HttpOnlyセッションCookieを使います。取得キーはアカウントのパスワードではなく、ログインや支払い管理の権限と同一ではありません。
初期確認にはhttps://api.redditapigateway.com/v1/search?q=onboarding&subreddit=SaaS&limit=3という小さな要求を利用できます。これはSaaSのonboardingに関する検索形式を示す例で、実応答の代わりになるものではありません。キーの置き換えはサーバー実行時に行います。二つのヘッダーを別々に試せば、成功するごとに一クレジットを使います。取得した結果のローカル分類や保存は、APIの追加呼び出しとは区別してください。
引数と結果の読み方
検索、投稿、コメントで使うフィルターはq、subreddit、author、kind、from、to、min_score、limit、pageです。kindの値はpostまたはcommentです。日付はUTCのYYYY-MM-DD形式で、toは指定日の終わりまでを含みます。min_scoreは最低スコア条件で、並べ替え指定ではありません。idは/v1/item専用で、投稿やコメント一覧のフィルターではありません。parent_idとlink_idも応答に現れる関係フィールドであり、検索引数ではありません。
一要求最大100レコード、一クエリ最大100ページという上限があります。各ページは成功時に個別課金されます。文書順は時間、関連度、スコアによる並べ替えではありません。総件数のeqは正確なレコード数、gteは下限、unknownまたはnullは信頼できる総数が不明な状態です。総数の単位はページではありません。正確な値でもクライアントが全件保存したことは証明せず、期間分割も網羅性や一意性を保証しません。
APIが返すデータはフラットなレコードであり、サーバーがスレッドツリーを組むわけではありません。返されたレコードに親フィールドが存在する場合、クライアント側でローカルにグループ化することが可能です。ただし、祖先の完全性や会話全体が保証されるわけではないため、結果の解釈には注意が必要です。 parent_idとlink_idがある場合の整理は、関係を分析したいときだけの任意処理です。通常の閲覧や件数集計にツリーは不要で、欠けた親は復元できません。コミュニティの集計値や接頭辞検索も、完全なアルファベット順一覧や正確な全体在庫として解釈しないでください。
エラー、費用、状態確認
400では未対応の引数、値、日付形式を修正します。401ではキーの欠落、有効性、別ドメインの値や再生成前の古い値を確認します。402はクレジット不足、429は要求頻度の制限です。原因ごとに対応し、頻度を下げて待機を入れる場合も再試行回数を制限してください。別アカウントで制限を避ける方法を設計に入れないでください。アーカイブ認証の前には、製品利用者の権限も自分のサーバーで確認する必要があります。
成功した取得要求は空の結果でも一クレジットです。無効な要求は差し引かれず、上流システムの失敗では予約分が戻ります。一方、クライアント側の接続切断はサーバー失敗の証拠ではありません。成功後に応答が失われたなら、成功した再試行にも費用がかかります。要求結果とローカル保存の結果を別に記録し、秘密ヘッダーはログから除外してください。読み取り専用でも固定応答や無料再試行は保証されません。
/v1/statusは認証不要かつ非課金で、静的なサービス範囲とHTTP応答を示します。検索エンジンや記録、キー、残高の検査は行わないため、実際の取得成功の代用にはなりません。製品側で独自の利用者上限や費用記録を加えることはできますが、それはAPIに組み込まれた利用者別クォータではありません。アカウントと残高はこのドメイン専用です。性能、記録保存、結果の網羅性についても保証を追加しないでください。
