公開ステータスとデータルート
ベースURLはhttps://api.redditgateway.comです。GET /v1/statusはキー不要で無料です。固定のサービス範囲とHTTPアプリケーションの応答を示します。アーカイブの接続先、検索の動作、記録の有無、残高は検査しません。検索の検査用として表示しないでください。後から送るデータ要求にはそれ自体の認証、上限、エラー処理が必要です。
GET /v1/searchは投稿とコメントの検索、/v1/postsは投稿、/v1/commentsはコメントの取得です。GET /v1/item?id=...では一件の識別子を指定します。idはitem専用で、postsやcommentsのフィルターではありません。GET /v1/subreddits?prefix=...はコミュニティ名の先頭部分で検索し、limitで要求件数を指定できます。コミュニティ集計の全体に対する正確性は保証されません。
保護された取得はAuthorization: Bearer YOUR_API_KEYとX-API-Key: YOUR_API_KEYの両方に対応します。一方を選んで実際のキーをサーバーから送ってください。アカウントパネルのSecure HttpOnly Cookieは別のセッションを管理し、APIキーヘッダーを置き換えません。アカウント、キー、残高はこのドメイン専用です。URLやブラウザーのコードではなく秘密設定を使用します。公開statusはキーの有効性も検査しません。
条件、ページ、結果の上限
検索、投稿、コメントではq、subreddit、author、kind、from、to、min_score、limit、pageを使用できます。日付はUTC基準のYYYY-MM-DD形式で、toの日付を含みます。min_scoreは最低スコアの条件であり、並べ替えではありません。parent_idとlink_idはクエリフィルターではなく、これらで全会話を要求する機能はありません。
kindパラメータはpostまたはcommentのいずれかを指定します。また、各リクエストで最大100レコード、1つのクエリで最大100ページまで処理可能です。ただし、ページを辿ることが完全なアーカイブのカバレッジを保証するわけではないため、データの完全性を前提にしすぎない設計が推奨されます。
limitは1～100、pageは1～100です。各ページは別の要求で、結果はアーカイブ文書順です。日時、関連度、スコア順ではありません。期間分割やページ反復は網羅性や重複のなさを保証しません。合計のeqは正確、gteは下限、unknownやnullは信頼できる合計がない状態を示します。合計はページ数ではなく記録数で、正確でも全件保存した証明ではありません。
APIの応答は、サーバー側でスレッドツリーとして組み立てられた複雑な構造ではなく、すべてフラットなレコードとして返されます。クライアント側で意図がある場合は、これらをローカルでグループ化できますが、サーバー側は会話の完全性や先祖情報の完全な提供を保証しません。 読む、分類する、数えるためのツリー構築は不要です。関係を調べる処理は任意で、存在するparent_idやlink_idを使っても欠けた親やコメントは復元されません。
失敗とキーの管理
HTTP 400は条件の形式や値の問題、HTTP 401はキーの不足または無効、HTTP 402はクレジット残高不足、HTTP 429は送信頻度の制限です。429は接続のタイムアウトではありません。条件とキーを修正し、頻度の制限では送信を待ちます。成功した取得は空でも一クレジットです。不正な要求は引き落とされず、上流障害では予約分が戻ります。
クライアントの接続切断は、サーバーで有料の成功が成立しなかった証拠にはなりません。成功した再試行は追加費用です。ネットワーク上の失敗とHTTP応答を分け、秘密ヘッダーを記録せずに保存済みの作業を追えるようにします。キーは登録時に支払い前に一度だけ表示されます。ログイン済みの利用者はパスワード確認で再発行でき、古いキーは直ちに無効になります。メール配送やパスワードリセット機能はありません。
