API ドキュメントを読む
どんな API ドキュメントの項目でも、動く curl コマンドに翻訳する
⏱ 想定 ~7 分
01 · 読む
スキルとは API を暗記することではありません。 どんな API ドキュメントでも読み、 2 分以内に動くリクエストに翻訳することです。
どの API にもドキュメントがあります。フォーマットは違っても構造は共通です: - メソッド + パス —— どのリクエストを送るか - path パラメータ —— URL パスに埋め込む値 - クエリパラメータ —— 任意のフィルターやオプション - リクエスト本文 —— POST/PUT で送る JSON - レスポンス —— 何が返ってくるか
ポイントまとめ
- {owner} のような path パラメータはそのまま URL パスに代入します
- クエリパラメータは ? のあとに置き、 required と書かれていなければ任意です
- POST/PUT のリクエスト本文フィールドは -d '{...}' で送ります
- ドキュメントの「Authentication」 (認証) のセクションは必ず先に読む
02 · コード例
本物の GitHub API ドキュメントの項目を一緒に読んでみましょう。
API ドキュメントの項目
GET /repos/{owner}/{repo}/issues
Path parameters:
owner (string, required) — account owner of the repository
repo (string, required) — name of the repository
Query parameters:
state (string) — "open", "closed", or "all" — default: "open"
labels (string) — comma-separated label names
per_page (integer) — results per page, max 100, default 30
page (integer) — page number of results
Response: Array of issue objects
curl コマンドへの翻訳
# Get all CLOSED issues for facebook/react, 10 per page
curl "https://api.github.com/repos/facebook/react/issues?state=closed&per_page=10"
翻訳の手順: 1. メソッド = GET → -X フラグは不要 2. base URL = https://api.github.com 3. パス = /repos/{owner}/{repo}/issues → {owner} を facebook 、 {repo} を react に置き換える 4. クエリパラメータ = ?state=closed&per_page=10 5. 公開リポジトリなので認証は不要
03 · 実機演習
自分でも試してみましょう。このコマンドを実行して facebook/react のクローズ済み issue を取得します。
curl "https://api.github.com/repos/facebook/react/issues?state=closed&per_page=5"
04 · 空欄補充
API ドキュメントには GET /repos/{owner}/{repo}/commits と書かれています。 torvalds/linux リポジトリのコミットを取得する場合、 URL パスはこうなります: /repos/___/linux/commits
05 · 実機演習
ここまでをまとめてみましょう。このドキュメント項目を、動く curl コマンドに翻訳します: GET /repos/{owner}/{repo}/commits クエリ: author (GitHub ユーザー名) 、 per_page (最大 100) タスク: torvalds/linux の直近 5 件のコミットを取得 (作者の絞り込みなし) 。
curl "https://api.github.com/repos/torvalds/linux/commits?per_page=5"
06 · クイズ
API ドキュメントには GET /users/{userId}/orders?status=pending&limit=50 と書かれています。ユーザー ID 42、ステータス pending、件数を 10 に制限した注文を取得したい。正しいパスは?
- /users?userId=42/orders?status=pending&limit=10
- /users/{42}/orders?status=pending&limit=10
- /users/42/orders?status=pending&limit=10
- /users/42/orders&status=pending&limit=10
07 · 空欄補充
API ドキュメントに GET /repos/{owner}/{repo}/commits と書かれているとき、 {owner} のような波カッコ部分は _____ パラメータと呼ばれます。
⚠ 全機能のインタラクティブ体験には JavaScript が必要です。JavaScript を有効にして再読み込みしてください。
※ このサイトは独立した教育プロジェクトで、Anthropic の公式製品ではありません。Claude™ は Anthropic, PBC の商標です。