はじめに

「API を叩いてデータを取得して…」

先輩エンジニアがこんな会話をしているのを聞いて、「APIって何…？」と思ったことはありませんか？

この記事では、APIの概念を 日常生活のたとえ から始めて、Web APIの仕組み、実際の使い方まで、初心者がしっかり理解できるように解説します。

1. APIとは

一言でいうと

API（Application Programming Interface） とは、ソフトウェア同士がやり取りするための窓口（インターフェース） です。

日常生活でたとえると

レストランで考えてみましょう：

あなた（お客さん）
  ↓ 注文する
ウェイター（= API）
  ↓ 注文を伝える
キッチン（= サーバー / システム）
  ↓ 料理を作る
ウェイター（= API）
  ↓ 料理を届ける
あなた（お客さん）

あなたはキッチンの中身を知らなくていい
ウェイターに「カレーください」と頼むだけ
ウェイター（API）が間を取り持ってくれる

APIも同じです。 システムの内部構造を知らなくても、決められたルールで「リクエスト」を送れば、「レスポンス」が返ってきます。

もう少し技術的にいうと

あなたのアプリ                    相手のシステム
┌─────────┐    リクエスト     ┌─────────┐
│         │ ──────────────→ │         │
│ クライアント │                │  サーバー  │
│         │ ←────────────── │         │
└─────────┘    レスポンス     └─────────┘
                ↑
           ここがAPI
     （やり取りのルール・窓口）

2. APIの種類

APIにはいくつかの種類があります。

種類	説明	例
Web API	インターネット経由でアクセスするAPI	天気予報API、Google Maps API
ライブラリAPI	プログラミング言語のライブラリが提供する機能	JavaのString クラスのメソッド群
OS API	OSが提供する機能	ファイル操作、ネットワーク通信
ハードウェアAPI	ハードウェアを制御するための機能	カメラ、GPS、センサー

💡 エンジニアが「API」と言うとき、多くの場合 Web API を指しています。この記事でも以降は Web API を中心に解説します。

3. Web API の仕組み

HTTPベースの通信

Web API は HTTP（Hypertext Transfer Protocol） という通信プロトコルを使います。
ブラウザでWebサイトを見るときと同じ仕組みです。

① クライアントが HTTPリクエスト を送る
② サーバーが処理する
③ サーバーが HTTPレスポンス を返す

HTTPメソッド

Web API では、何をしたいか を HTTP メソッドで表現します。

メソッド	意味	操作	例
GET	取得する	データを読み取る	ユーザー情報を取得
POST	作成する	新しいデータを送る	新規ユーザー登録
PUT	更新する	データを丸ごと書き換える	プロフィール全体を更新
PATCH	一部更新する	データの一部を書き換える	メールアドレスだけ更新
DELETE	削除する	データを消す	ユーザーを削除

💡 覚え方: CRUD操作と対応しています。
Create = POST / Read = GET / Update = PUT・PATCH / Delete = DELETE

リクエストとレスポンスの具体例

リクエスト（ユーザーID: 1 の情報を取得）：

GET /api/users/1 HTTP/1.1
Host: example.com
Accept: application/json

レスポンス：

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "name": "田中太郎",
  "email": "tanaka@example.com",
  "age": 25
}

4. REST API とは

RESTの概念

Web API の中でも最も広く使われているのが REST API（RESTful API） です。

REST（Representational State Transfer） は、Web API を設計するための アーキテクチャスタイル（設計思想） です。

REST API の主な特徴

原則	説明
リソース指向	データを「リソース」として URL で表現する
HTTPメソッドの活用	操作の種類を HTTP メソッドで表す
ステートレス	リクエストごとに独立（前回のやり取りを記憶しない）
統一インターフェース	一貫したルールでアクセスできる

RESTful な URL 設計

# ユーザー一覧を取得
GET /api/users

# ユーザーID: 1 を取得
GET /api/users/1

# 新規ユーザーを作成
POST /api/users

# ユーザーID: 1 を更新
PUT /api/users/1

# ユーザーID: 1 を削除
DELETE /api/users/1

# ユーザーID: 1 の注文一覧を取得
GET /api/users/1/orders

💡 ポイント: URL は 名詞（リソース名） で表し、動詞（操作） は HTTP メソッドで表現します。

✅ GET /api/users （良い例）

❌ GET /api/getUsers （悪い例 ― URL に動詞が入っている）

5. ステータスコード

API のレスポンスには ステータスコード が含まれます。これは「リクエストの結果」を表す3桁の数字です。

よく使うステータスコード

コード	意味	説明
200	OK	リクエスト成功
201	Created	リソースの作成に成功
204	No Content	成功したが返すデータなし（削除時など）
400	Bad Request	リクエストの内容が不正
401	Unauthorized	認証が必要（ログインしていない）
403	Forbidden	アクセス権限がない
404	Not Found	リソースが見つからない
405	Method Not Allowed	そのHTTPメソッドは許可されていない
500	Internal Server Error	サーバー側でエラーが発生

カテゴリで覚える

範囲	カテゴリ	意味
1xx	情報	処理中（あまり見かけない）
2xx	成功	リクエストが正常に処理された
3xx	リダイレクト	別の場所に転送
4xx	クライアントエラー	リクエスト側に問題がある
5xx	サーバーエラー	サーバー側に問題がある

💡 覚え方: 4xx は「あなた（クライアント）が悪い」、5xx は「サーバーが悪い」

6. データ形式：JSON

Web API でデータをやり取りする際、最も広く使われているのが JSON（JavaScript Object Notation） です。

JSON の基本構文

{
  "name": "田中太郎",
  "age": 25,
  "isStudent": false,
  "skills": ["Java", "Python", "SQL"],
  "address": {
    "city": "東京",
    "zipCode": "100-0001"
  }
}

JSON のルール

ルール	説明
キーはダブルクォーテーションで囲む	`"name"` ✅ / `'name'` ❌ / `name` ❌
文字列はダブルクォーテーションで囲む	`"東京"` ✅ / `'東京'` ❌
数値・真偽値・null はそのまま	`25`, `true`, `null`
末尾のカンマは禁止	`{"a": 1,}` ❌
コメントは書けない	`// コメント` ❌

7. 認証と認可

多くの API はだれでも自由にアクセスできるわけではありません。認証（Authentication） と 認可（Authorization） の仕組みがあります。

認証と認可の違い

項目	認証（Authentication）	認可（Authorization）
意味	あなたは誰？を確認する	何をしていい？を確認する
例	ログイン（ID/パスワード入力）	管理者のみ削除可能

よく使われる認証方式

1. APIキー

最もシンプルな方式。発行されたキーをリクエストに含めます。

# ヘッダーに含める場合
curl -H "X-API-Key: abc123xyz" https://api.example.com/data

# クエリパラメータに含める場合
curl https://api.example.com/data?api_key=abc123xyz

2. Bearer トークン（JWT など）

ログイン後に発行されるトークンを使う方式。現在最も一般的です。

# 1. ログインしてトークンを取得
curl -X POST https://api.example.com/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "pass123"}'

# レスポンス: {"token": "eyJhbGciOiJIUzI1NiIs..."}

# 2. トークンを使ってAPIにアクセス
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.example.com/users/me

3. OAuth 2.0

Google や GitHub など外部サービスのアカウントでログインする方式。

ユーザー → あなたのアプリ → Google（認証画面）→ 許可 → アクセストークン発行 → API利用

💡 初心者はまず API キーと Bearer トークンを理解しておけば十分です。

8. 実際にAPIを使ってみよう

curl コマンドで試す

ターミナル（コマンドプロンプト）から API を呼び出せます。

# 天気情報を取得（Open-Meteo API ― 無料・登録不要）
curl "https://api.open-meteo.com/v1/forecast?latitude=35.6895&longitude=139.6917&current_weather=true"

レスポンス例：

{
  "current_weather": {
    "temperature": 18.5,
    "windspeed": 12.3,
    "weathercode": 0,
    "time": "2026-02-15T12:00"
  }
}

Java で API を呼び出す

Java 11 以降の HttpClient を使った例：

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ApiExample {
    public static void main(String[] args) throws Exception {
        // HTTPクライアントを作成
        HttpClient client = HttpClient.newHttpClient();

        // リクエストを作成
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.open-meteo.com/v1/forecast"
                + "?latitude=35.6895&longitude=139.6917&current_weather=true"))
            .GET()
            .build();

        // リクエストを送信してレスポンスを受け取る
        HttpResponse<String> response =
            client.send(request, HttpResponse.BodyHandlers.ofString());

        // ステータスコードを確認
        System.out.println("ステータス: " + response.statusCode());

        // レスポンスボディを表示
        System.out.println("レスポンス: " + response.body());
    }
}

JavaScript（fetch）で API を呼び出す

// ブラウザの開発者ツール（Console）で試せます
fetch("https://api.open-meteo.com/v1/forecast?latitude=35.6895&longitude=139.6917&current_weather=true")
  .then(response => response.json())
  .then(data => {
    console.log("気温:", data.current_weather.temperature, "°C");
    console.log("風速:", data.current_weather.windspeed, "km/h");
  })
  .catch(error => console.error("エラー:", error));

9. APIドキュメントの読み方

API を使うとき、APIドキュメント（API仕様書） を読む力が重要です。

ドキュメントに書かれている主な情報

項目	説明	例
エンドポイント	APIのURL	`GET /api/users/{id}`
HTTPメソッド	操作の種類	GET, POST, PUT, DELETE
パラメータ	リクエストに含める値	クエリパラメータ、パスパラメータ
リクエストボディ	送信するデータの形式	JSON の構造
レスポンス	返却されるデータの形式	JSON の構造、ステータスコード
認証方法	必要な認証情報	APIキー、Bearerトークン

ドキュメントの読み方（例）

POST /api/users
  Summary: 新規ユーザーを作成する

  Headers:
    Authorization: Bearer {token}    (必須)
    Content-Type: application/json   (必須)

  Request Body:
    {
      "name": "string"     (必須) ユーザー名
      "email": "string"    (必須) メールアドレス
      "age": "integer"     (任意) 年齢
    }

  Responses:
    201 Created       → 作成成功（作成されたユーザー情報を返す）
    400 Bad Request   → 必須項目が不足 or 形式が不正
    401 Unauthorized  → 認証トークンが無効
    409 Conflict      → メールアドレスが既に登録済み

Swagger / OpenAPI

多くの API は Swagger UI というインタラクティブなドキュメントを提供しています。ブラウザ上でAPIを試せるので、初心者にもわかりやすいです。

10. API を使うときの注意点

レートリミット（Rate Limit）

多くの API は 一定時間あたりのリクエスト数に制限 を設けています。

例: 1分間に60リクエストまで
    → 1秒に1回以上は送らない

制限を超えると 429 Too Many Requests が返されます。

APIキーの管理

// ❌ NG: ソースコードにAPIキーを直書き
String apiKey = "sk-abc123xyz789";

// ✅ OK: 環境変数から読み込む
String apiKey = System.getenv("API_KEY");

APIキーをソースコードに書いて GitHub に公開してしまう事故が非常に多いです。絶対にソースコードに直書きしないでください。

エラーハンドリング

API は必ずしも成功するとは限りません。ネットワーク障害やサーバーダウンに備えましょう。

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

switch (response.statusCode()) {
    case 200:
        System.out.println("成功: " + response.body());
        break;
    case 401:
        System.out.println("認証エラー: トークンを確認してください");
        break;
    case 404:
        System.out.println("リソースが見つかりません");
        break;
    case 429:
        System.out.println("リクエスト制限に達しました。少し待ってから再試行してください");
        break;
    default:
        System.out.println("エラー: " + response.statusCode());
}

11. よく使われる公開API

学習に使える無料の公開APIを紹介します。

API	説明	認証	URL
Open-Meteo	天気予報	不要	https://open-meteo.com/
JSONPlaceholder	ダミーデータ（学習用）	不要	https://jsonplaceholder.typicode.com/
PokeAPI	ポケモンデータ	不要	https://pokeapi.co/
GitHub API	GitHubのリポジトリ情報	一部不要	https://docs.github.com/en/rest
OpenWeatherMap	天気予報	APIキー（無料枠あり）	https://openweathermap.org/api
Google Maps API	地図・位置情報	APIキー	https://developers.google.com/maps

💡 おすすめ: まずは認証不要の JSONPlaceholder で GET / POST / PUT / DELETE を一通り試してみましょう！

JSONPlaceholder で練習

# ユーザー一覧を取得
curl https://jsonplaceholder.typicode.com/users

# 投稿ID: 1 を取得
curl https://jsonplaceholder.typicode.com/posts/1

# 新しい投稿を作成
curl -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{"title": "テスト投稿", "body": "本文です", "userId": 1}'

# 投稿ID: 1 を更新
curl -X PUT https://jsonplaceholder.typicode.com/posts/1 \
  -H "Content-Type: application/json" \
  -d '{"title": "更新後のタイトル", "body": "更新後の本文", "userId": 1}'

# 投稿ID: 1 を削除
curl -X DELETE https://jsonplaceholder.typicode.com/posts/1

まとめ

項目	内容
API とは	ソフトウェア同士がやり取りするための窓口
Web API	HTTP を使ってインターネット経由でアクセスする API
REST API	リソース指向・HTTPメソッド活用の設計思想
HTTPメソッド	GET（取得）, POST（作成）, PUT（更新）, DELETE（削除）
ステータスコード	2xx 成功 / 4xx クライアントエラー / 5xx サーバーエラー
JSON	API でデータをやり取りする標準フォーマット
認証	APIキー、Bearer トークン、OAuth 2.0
注意点	レートリミット、APIキーの管理、エラーハンドリング

次のステップ

JSONPlaceholder で CRUD 操作を一通り試す
Swagger UI のあるAPIドキュメントを読んでみる
Java や JavaScript で実際に API を呼び出すコードを書く
自分で REST API を作ってみる（Spring Boot, Express.js など）

記事が参考になったら「いいね」していただけると励みになります！

@kotaro_ai_lab