最初のリクエスト
サーバーからリクエストを送信し、APIキーを非公開にしてください。
: "${REDDITAPP_API_KEY:?Set REDDITAPP_API_KEY on your server}"
curl --get --fail-with-body 'https://api.redditapp.com/v1/search' \
-H "Authorization: Bearer ${REDDITAPP_API_KEY}" \
--data-urlencode 'q=offline maps' \
--data-urlencode 'subreddit=hiking' \
--data-urlencode 'limit=3'APIリファレンス
↔ 表を横にスクロールできます
APIエンドポイント
| メソッド | エンドポイント | パラメータ |
|---|---|---|
GET | /v1/search | q, subreddit, author, kind, from, to, min_score, limit, page |
GET | /v1/posts | q, subreddit, author, kind, from, to, min_score, limit, page |
GET | /v1/comments | q, subreddit, author, kind, from, to, min_score, limit, page |
GET | /v1/item | id |
GET | /v1/subreddits | prefix, limit |
GET | /v1/status | — |
補足事項
GET | /v1/search · /v1/posts · /v1/comments · /v1/item · /v1/subreddits · /v1/status |
|---|---|
q · subreddit · author · kind | kind: post | comment |
from · to | YYYY-MM-DD |
min_score | score ≥ min_score |
limit · page | 1…100 · 1…100 |
/v1/item | id |
/v1/subreddits | prefix · limit |
_doc | ≠ date · ≠ relevance · ≠ score |
pagination.relation | eq · gte · unknown |
pagination | has_more · window_exhausted · truncated |
1 credit | $0.001 |
$1 | 1000 credits |
$50 | 50000 credits |
400 · 401 · 402 · 429 · 502 | HTTP |
アプリとアーカイブの間にバックエンドを置く
説明用のハイキング機能では、モバイルまたはWebクライアントがoffline mapsという語句を自分のバックエンドへ送ります。バックエンドはリクエストを検証し、アプリ側の上限を適用して、保存済みのサービスキーでアーカイブを呼び出します。閲覧画面に必要なフィールドだけを返してください。これは設計の出発点であり、このテナントでハイキングのレコードを取得できたという主張ではありません。
GET https://api.redditapp.com/v1/search?q=offline%20maps&subreddit=hiking&limit=3&page=1を使います。バックエンドからX-API-Key: YOUR_SAVED_KEYまたはAuthorization: Bearer YOUR_SAVED_KEYのいずれかをヘッダーで送信してください。認証情報をURL、クライアントの配布コード、公開ログに含めないでください。アカウントページのセッションCookieは、取得APIの認証の代わりにはなりません。
サービスが受け付けるフィルターを選ぶ
検索ではq、subreddit、author、kind、from、to、min_score、limit、pageを指定できます。qはtitleとtextを対象にAND検索を行いますが、完全なフレーズ一致や意味に基づく一致を保証するものではありません。kindに指定できるのはpostまたはcommentです。subredditとauthorは各フィールドの完全一致フィルターです。min_scoreはレコードを絞り込むもので、並べ替えは行いません。
fromとtoにはUTCの日付をYYYY-MM-DD形式で指定します。toには、そのUTC日の終わりまでが含まれます。例えばfrom=2025-01-01とto=2025-12-31は日付の範囲を定めますが、日付順の並べ替えは要求しません。ISO形式の日時文字列、任意のクエリDSL、sortパラメーター、parent_id/link_idフィルターは送らないでください。未対応のパラメーターは拒否されます。
目的に合うエンドポイントを使う
GET /v1/postsとGET /v1/commentsはレコードの種類を限定し、検索フィルターを受け付けます。idは必須ではありません。GET /v1/item?id=RECORD_IDは、取得可能なレコードをidで検索します。GET /v1/subreddits?prefix=hik&limit=3は範囲を限ったsubredditの集計を返します。その件数がアーカイブ全体で厳密に正しいとは保証されません。
GET /v1/statusは公開されており、クレジットを消費しません。過去のアーカイブであることを示す固定情報を返し、HTTPハンドラーが応答したことを確認できます。検索バックエンドへの問い合わせ、収録範囲の確認、アーカイブの健全性の測定は行いません。これらのエンドポイントは、投稿、投票、メッセージ、アカウントのブックマーク、完全な会話ツリーを提供しません。
「さらに表示」を作る前にページネーションを読む
取得レスポンスにはdata、pagination、creditsが含まれます。dataのレコードは上流の平坦なソースオブジェクトです。使いたいタイトル、投稿者、日付、permalinkがない場合もあります。アーカイブは_doc順を使い、時系列、関連度、スコアの順には並びません。取得済みの一部をアプリ内で並べ替えることはできますが、アーカイブ全体で最新または最上位の部分集合にはできません。
pagination.pageを増やすときはフィルターとlimitを変えないでください。pagination.has_moreは、可能な場合に先読みレコードを使って判定されます。falseなら自動で次のリクエストを出す操作を設けないでください。pagination.window_exhaustedは、取得範囲の最終ページに達した状態を示します。そこまで取得しても、一致するアーカイブ内の資料をすべて取得したとは限りません。
レコード数の指定範囲は1–100、ページは1–100です。pagination.totalはpagination.relationと併せて読みます。eqはレスポンスの件数定義における確定値、gteは下限値、unknownは信頼できる総数がないことを示し、値がnullの場合もあります。2ページ目以降が空でも、総数は確定できません。limitが100で100ページ目が満杯なら先読みの余地がなく、総数は下限値となります。ページ上限ではhas_moreはfalseです。subredditの集計ではtotalは不明で、pagination.truncatedが集計から省かれたバケットの有無を示します。
課金と失敗を明確に扱う
正常な取得は、data配列が空でも1クレジットを消費します。送信前に入力を検証し、読み込み表示を動かすだけのためにページを取得しないでください。HTTP 400は入力の不備、401はサービスキーの欠如または無効、402はクレジット不足、429はレート制限を表します。このように拒否されたリクエストでは、取得用クレジットは予約されません。
上流へのリクエスト失敗はHTTP 502として返され、予約済みクレジットが返還されるか、返還の照合処理待ちであることが示されます。アプリとの通信の途中でレスポンスが失われた場合、処理結果は不明です。無料だったと決めつけないでください。クエリの状態を保持し、Retry-Afterに従い、適切な場合に利用者が再試行を選べるようにします。認証情報と残高への対応は運用担当者の仕事であり、ハイキング利用者の仕事ではありません。
レスポンスを誤解のない閲覧画面にする
レコードの文章は表示前にエスケープしてください。出典を識別する情報や出典リンクがあれば保持し、日付がなければ不明と示します。レコードの作成日時とアプリの取得日時も区別してください。親やリンクの識別子は、存在する場合に端末内でのグループ化に使えますが、欠けた祖先レコードを補うものではありません。
「画面の状態」で、読み込み中、結果なし、失敗時のメッセージ案を説明します。「アプリの流れ」の実装ノートでは、カード、端末内に保存する参照先、リクエスト予算を扱います。「キーとクレジット」にはアカウントの準備と料金をまとめています。実装は自分で確認し、テストしてください。これらの例は稼働中の機能や現在の登山道に関する助言を実証するものではありません。
