API とは何か ― リクエストの中身から GitHub API を呼ぶまで

「この機能は外部の API を使えばすぐできます」「API の仕様書を読んでおいて」。開発の現場に入ると、API という言葉を毎日のように聞きます。ところが、何となく「データをもらう仕組み」くらいの理解のまま、仕様書を前に手が止まってしまう人も少なくありません。

この記事では、新人・勉強中のエンジニア向けに、API の考え方から、実際に呼び出してデータを取るところまでを、一度で通して説明します。例には、誰でも無料で試せる GitHub の API を使います。内容は 2026 年 11 月 8 日時点で、MDN と GitHub の公式ドキュメントを確認し、コードも実際に動かして確かめたものです。

API とは：アプリ同士の「注文の窓口」

API は Application Programming Interface の略で、「プログラムから別のソフトウェアの機能やデータを使うための決まった入口」のことです。

レストランにたとえると、わかりやすくなります。客は厨房に入って自分で料理を作りません。メニューを見て、店員に「これを 1 つ」と注文し、出てきた料理を受け取ります。厨房の中で何が起きているかは知らなくてかまいません。

• メニュー：何を頼めるか、どう頼めばよいかが書いてある → API のドキュメント（仕様書）
• 店員への注文 → リクエスト
• 出てくる料理 → レスポンス
• 厨房 → 相手のシステムの内部（データベースやプログラム）

API の良いところは、この「厨房に入らなくていい」点にあります。相手のシステムの作りを知らなくても、決められた形で注文すれば、決められた形で結果が返ってきます。逆に相手のシステムは、中身を作り直しても、窓口の形さえ変えなければ、使う側に影響を与えません。決済、地図、天気、SNS、社内の在庫管理など、今の Web サービスの多くは、こうした窓口を組み合わせて作られています。

API という言葉自体はもっと広い意味を持ち、プログラミング言語のライブラリの関数の集まりなども API と呼びます。この記事では、Web 開発で一番よく使う「HTTP で呼び出す Web API」に絞って説明します。

リクエストとレスポンスの中身

Web API とのやりとりは、ブラウザが Web ページを表示するときと同じ HTTP という仕組みで行います。違いは、返ってくるのが人が読む画面（HTML）ではなく、プログラムが読みやすいデータ（多くは JSON）である点です。

リクエスト：何を、どう頼むか

メソッドは、注文の種類を表します。MDN の説明をもとにまとめると、次のとおりです。

「安全」は、サーバーのデータを変えないことです。「冪等（べきとう）」は、同じリクエストを何回送っても結果が 1 回送ったときと同じになることです。たとえば通信が途中で切れたとき、GET や PUT なら送り直しても問題ありません。一方、POST を送り直すと、同じデータが 2 件作られてしまうことがあります。再送やリトライの処理を書くときに、この違いが効いてきます。

レスポンス：結果がどうだったか

レスポンスは、ステータスコード・ヘッダー・ボディの 3 つでできています。まず見るべきなのが、結果を 3 桁の数字で表すステータスコードです。百の位で 5 つに分類されています。

4xx と 5xx の区別は、エラーの原因を探すときの最初の手がかりです。4xx なら、まず自分のリクエスト（URL・パラメータ・認証）を疑います。5xx なら相手側の問題なので、時間を置いて試すか、相手に問い合わせます。401 と 403 の違いも覚えておきましょう。401 は「誰なのかわからない（認証していない）」、403 は「誰なのかはわかったが、その操作は許されていない」という意味です。

ボディには、注文の結果のデータが入ります。Web API では JSON という形式がよく使われます。名前と値の組を {} で囲んだ、プログラムで扱いやすい書き方です。

実際に呼んでみる：GitHub の API

ここからは手を動かします。GitHub の「リポジトリの情報を取得する」API は、公開されているリポジトリなら認証なしで呼び出せます。

curl で呼ぶ

curl は、ターミナルから HTTP のリクエストを送れるコマンドです。-i を付けると、ステータスコードとヘッダーも表示されます。

curl -i \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/repos/laravel/laravel

Accept は「この形式で返してほしい」、X-GitHub-Api-Version は「この版の API の決まりで答えてほしい」という指定です。どちらも GitHub のドキュメントで推奨されています。実行すると、次のような結果が返ってきます（一部を抜き出しています）。

HTTP/2 200
content-type: application/json; charset=utf-8
x-ratelimit-limit: 60
x-ratelimit-remaining: 59

{
  "full_name": "laravel/laravel",
  "language": "Blade",
  "default_branch": "13.x",
  "stargazers_count": 85392,
  ...
}

1 行目の 200 が成功を表し、ボディの JSON にリポジトリの情報が入っています。x-ratelimit- で始まるヘッダーについては、次の節で説明します。URL のリポジトリ名を、存在しない名前に変えて試してみてください。今度は 404 が返るはずです。

なお、API での 404 は「URL が間違っている」だけでなく、「URL の形は正しいが、指定したデータが存在しない」という意味でも返ってきます。MDN もこの点を説明しています。404 が出たら、エンドポイントのつづりと、指定した ID や名前の両方を疑ってください。

JavaScript の fetch で呼ぶ

ブラウザや Node.js では、fetch で同じことができます。

async function getRepo(owner, repo) {
  const response = await fetch(`https://api.github.com/repos/${owner}/${repo}`, {
    headers: {
      Accept: "application/vnd.github+json",
      "X-GitHub-Api-Version": "2026-03-10",
    },
  });

  // 404 や 500 でも fetch はエラーにならないので、自分で確かめる
  if (!response.ok) {
    throw new Error(`Response status: ${response.status}`);
  }

  const repoData = await response.json();
  console.log(`${repoData.full_name}: ★${repoData.stargazers_count}`);
}

getRepo("laravel", "laravel").catch((error) => console.error(error.message));

認証と、キーの扱い

さきほどのレスポンスにあった x-ratelimit-limit: 60 は、「1 時間に 60 回まで」という意味です。GitHub の API は、認証なしのリクエストを送り元の IP アドレスごとに数え、1 時間に 60 回までしか受け付けません。残りの回数が x-ratelimit-remaining、回数が戻る時刻が x-ratelimit-reset です。超えると 403 か 429 が返ってきます。

回数制限を超えたときは、すぐに送り直してはいけません。GitHub のドキュメントは、x-ratelimit-reset の時刻まで待ってから送るよう求めていて、制限中に送り続けると、連携そのものを止められることがあるとしています。ループの中で API を呼ぶ処理を書くときは、残りの回数を見て待つ処理を入れるか、必要なデータをまとめて取る方法がないかを先に調べましょう。

本格的に使うときは、自分が誰なのかを伝える「認証」をします。多くの API では、発行してもらったトークン（API キー）を、リクエストのヘッダーに付けて送ります。

curl -H "Authorization: Bearer <発行したトークン>" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/laravel/laravel

GitHub の場合、個人のトークンで認証すると、上限は 1 時間に 5,000 回に増えます。認証しないと使えない機能（非公開のデータや、書き込みの操作など）も使えるようになります。

トークンは、あなたとして API を使うための「合い鍵」です。漏れれば、他人があなたになりすましてデータを読んだり消したりできます。GitHub のドキュメントが挙げている注意点のうち、特に大事なものは次のとおりです。

• コードに直接書かない。.env などの設定ファイルや、シークレットの管理機能に置き、リポジトリには入れない
• 権限は必要最小限にし、有効期限を付ける
• チャットやメールに貼らない。共有するときは、パスワード管理ツールなどの安全な方法を使う
• 漏れたかもしれないときは、すぐに新しいトークンを発行し、古いものを無効にする

ブラウザで動く JavaScript にトークンを書くのも危険です。ページを開いた人なら誰でも中身を見られるからです。トークンが必要な API は、サーバー側のプログラムから呼び出すのが基本です。

初めての API ドキュメントで確かめること

API ごとに書き方は違いますが、ドキュメントで探す項目はだいたい共通です。初めて使う API では、次の順に確かめると迷いにくくなります。

• エンドポイントとメソッド：やりたいことに対応する URL と、GET・POST などのどれを使うか
• 認証の方法：認証なしで使えるか。トークンはどこで発行し、どのヘッダーで送るか
• パラメータ：URL に入れる値、クエリ文字列、ボディで送る項目。必須か任意か
• レスポンスの形：成功したときに返る JSON の例と、各項目の意味
• エラー：どんなときに何番のステータスコードが返るか
• 回数制限：何回まで呼べるか。超えたらどうなるか
• バージョン：API の版の指定方法と、古い版がいつまで使えるか

わからないときは、まずドキュメントにある curl の例をそのまま実行してみるのがおすすめです。動く例を手元で確かめてから、少しずつ自分のコードに書き換えていくと、どこで失敗しているかを切り分けやすくなります。

まとめ

• API は、相手のシステムの中身を知らなくても、決まった形で注文すれば決まった形で結果が返ってくる「窓口」です
• リクエストは URL・メソッド・ヘッダー・ボディ、レスポンスはステータスコード・ヘッダー・ボディでできています。エラーの原因は、まず 4xx か 5xx かで切り分けます
• トークンは合い鍵です。コードに書かず、最小の権限と期限を付けて扱います

次の一歩として、仕事で使う予定の API のドキュメントを開き、上のチェックリストの項目を順に探してみてください。

参考リンク

• HTTP request methods - MDN
• HTTP response status codes - MDN
• Using the Fetch API - MDN
• REST API endpoints for repositories - GitHub Docs
• Rate limits for the REST API - GitHub Docs
• Keeping your API credentials secure - GitHub Docs