API ドキュメント
API キーの正しい送信、レスポンス構造の選択、最初のリクエスト、エラー処理、テストデータの検証をまとめた簡潔な連携リファレンスです。
このページには、特定の API メソッドに依存しないルールをまとめています：認証、レスポンスのバージョン、エラー処理、再試行、テスト API の使い方、本番前の確認です。
メソッド固有のパラメーター、スキーマ、例については API リファレンスを使用してください。カバー範囲とメソッドのグループを比較するには、プラットフォームのページを使用してください。
プラットフォーム API へのすべてのリクエストで、API キーを `X-API-Key` ヘッダーに含めて送信してください。
キーはダッシュボードのセッションから引き継がれません。バックエンドサービス、ワーカー、バックグラウンドジョブは、このヘッダーを明示的に送信する必要があります。
V1 と V2 は同じ API メソッドのカタログを提供しますが、返すデータ構造が異なります。クライアントを構築する前にバージョンを選び、連携の設定で固定してください。
同じ処理フローで V1 と V2 を混在させないでください。マッピング、キャッシュ、テスト、保守が複雑になります。
ソースプラットフォームのレスポンスの形を、ScrapeStorm による最小限の変更で維持します。
移行、後方互換性、既にプラットフォーム固有のフィールドに依存しているクライアント。
製品コード、分析、社内サービスのために、より安定したデータ契約を提供します。
新しい連携、新しいサービス、ソースプラットフォームのデータ形式を必要としないすべてのコード。
バージョンを選んだら、ライブ API のメソッドで連携を確認します：ベース URL、ヘッダー、クエリパラメーター、タイムアウト、エラー処理です。
| HTTP メソッド | GET |
|---|---|
| エンドポイント | /api/v2/youtube.com/profile/about-by-user-identifier |
| クエリパラメーターの例 | user_identifier=mkbhd |
| ヘッダー | X-API-Key |
この例では YouTube の API メソッド `profile/about-by-user-identifier` を使用しています。`user_identifier` は、ご自身のシナリオのテスト用 ID に置き換えてください。
V1 と V2 のプラットフォーム API の公開メソッドは、同じ外側のエンベロープ `success`、`status`、`data` を使用します。コレクションのメソッドでは、最上位に `pagination` が含まれる場合もあります。
バージョンの選択で変わるのは `data` 内のスキーマであり、通信のエンベロープではありません。選択したメソッドの正確なフィールドは API リファレンスを参照してください。
| レスポンスの種類 | 最上位のフィールド | 最初に読むべきもの |
|---|---|---|
| 成功したレスポンス |
success,
status,
data
|
`data` にメソッドのデータが含まれます。 |
| ページ分割された成功レスポンス |
success,
status,
pagination,
data
|
`pagination` は最上位にあり、メソッドのデータは `data` に残ります。 |
| エラーレスポンス |
success,
status,
error,
meta
|
HTTP ステータスと `error.code` で分岐します。 |
エラーは共通のエンベロープを使用します。HTTP ステータスと `error.code` で分岐してください。`message` フィールドは表示やログ用であり、アプリケーションの制御フローには使用しないでください。
| HTTP ステータス | エラーコード | クライアントの対応 |
|---|---|---|
| 401 |
認証されていません
UNAUTHORIZED
|
API キーと環境を確認してください。同じキーで同じリクエストをループで再試行しないでください。 |
| 422 |
検証に失敗しました
VALIDATION_FAILED
|
リクエストのパラメーターを修正してください。同じ入力では同じエラーが返されます。 |
| 402 |
クレジットが不足しています
INSUFFICIENT_CREDITS
|
残高またはアカウントの制限が更新されるまで、処理を停止してください。 |
| 429 |
同時接続数の上限を超えました
CONCURRENT_CONNECTIONS_EXCEEDED
|
API キーごとの並列処理を減らすか、リクエストをキューに入れてください。 |
| 429 |
レート制限を超えました
RATE_LIMIT_EXCEEDED
|
指定された再試行の間隔を待ち、ワーカー間で再試行を調整してください。 |
| 503 |
エンドポイントを利用できません
ENDPOINT_UNAVAILABLE
|
他のメソッドが動作している場合は、連携全体を停止するのではなく、メソッド単位でバックオフを適用してください。 |
| 500 |
サーバー内部エラー
INTERNAL_SERVER_ERROR
|
上限付きのバックオフで再試行してください。試行回数の上限に達したら、失敗をログに記録し、監視を通じてエスカレーションしてください。 |
テスト API のメソッドは、ソースプラットフォームを呼び出さずに静的な JSON の例を返します。クライアント、画面、パーサーのテストの開発に使用してください。
| テスト API | https://www.scrapestorm.net/api-mock |
|---|---|
| 例 | https://www.scrapestorm.net/api-mock/v2/youtube.com/profile/about-by-user-identifier?user_identifier=mkbhd |
| API リファレンス |
実際のトラフィックを流し、ワーカーの並列度を上げる前に、これらの確認を行ってください。
新しいクライアントは V2 を使用します。V1 は、既存の連携の互換性や移行のためにのみ許可されます。
キーはシークレットストアにあり、フロントエンドのコード、公開リポジトリ、クライアントバンドル、ログには含まれていません。
クライアントの分岐は HTTP ステータスと `error.code` に依存しています。`message` はビジネスロジックで使用されていません。
`RATE_LIMIT_EXCEEDED` は `Retry-After` または `error.retry_after_seconds` を待ちます。`402` と `422` は同じ入力で再試行しません。`500` と `503` にはバックオフと試行回数の上限があります。
キューまたはレートリミッターが、ワーカー、cron ジョブ、バックグラウンドプロセスからの同時リクエストを制限しています。
テストデータはデータの形を検証します。ライブ API は実際のパラメーター、制限、可用性、クレジットの消費を検証します。
トラフィックが増える前に、使用する API メソッドのコストを確認してください。
各メソッドの具体的なパラメーター、スキーマ、例については、必要なバージョンの API リファレンスを開いてください。ソースとメソッドのグループを選ぶには、プラットフォームを使用してください。