Web APIとは？初心者向けにわかりやすく解説

APIとは

API（Application Programming Interface）は、異なるソフトウェア同士が情報をやり取りするための「窓口」です。Web APIを使うことで、他のサービスの機能やデータを自分のアプリケーションで利用できます。

身近なAPIの例

REST APIの基本

現在最も一般的なWeb APIの形式がREST（Representational State Transfer）APIです。HTTPプロトコルを使ってデータをやり取りします。

HTTPメソッド（CRUD操作）

REST APIでは、データの操作に応じて異なるHTTPメソッドを使います。

// HTTPメソッドと操作の対応
GET    → データの取得（Read）
POST   → データの作成（Create）
PUT    → データの完全な更新（Update）
PATCH  → データの部分的な更新（Update）
DELETE → データの削除（Delete）

// URLの例（ユーザー管理API）
GET    /api/users      → 全ユーザー一覧を取得
GET    /api/users/1    → ID:1のユーザーを取得
POST   /api/users      → 新しいユーザーを作成
PUT    /api/users/1    → ID:1のユーザーを更新
DELETE /api/users/1    → ID:1のユーザーを削除

ステータスコード

APIのレスポンスには結果を示すステータスコードが含まれます。

// 成功系（2xx）
200 OK            → リクエスト成功
201 Created       → 新規リソース作成成功
204 No Content    → 成功（レスポンスボディなし）

// クライアントエラー（4xx）
400 Bad Request   → リクエストが不正
401 Unauthorized  → 認証が必要
403 Forbidden     → アクセス権限なし
404 Not Found     → リソースが存在しない
429 Too Many Requests → レート制限超過

// サーバーエラー（5xx）
500 Internal Server Error → サーバー内部エラー
503 Service Unavailable   → サービス一時停止

Fetch APIの使い方

JavaScript/TypeScriptでAPIを呼び出すには、標準のfetch関数を使います。

GETリクエスト（データ取得）

// シンプルなGETリクエスト
async function getUsers() {
  const response = await fetch("https://api.example.com/users");

  // レスポンスのステータスチェック
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  // JSONとしてパース
  const users = await response.json();
  console.log(users);
  return users;
}

// 実行
getUsers().then(data => console.log(data));

POSTリクエスト（データ作成）

async function createUser(userData) {
  const response = await fetch("https://api.example.com/users", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(userData),
  });

  if (!response.ok) {
    throw new Error("ユーザー作成に失敗しました");
  }

  const newUser = await response.json();
  return newUser;
}

// 使用例
const newUser = {
  name: "田中太郎",
  email: "tanaka@example.com",
  age: 25
};

createUser(newUser).then(user => {
  console.log("作成されたユーザー:", user);
});

エラーハンドリング

async function fetchWithErrorHandling(url) {
  try {
    const response = await fetch(url);

    // HTTPエラーチェック
    if (!response.ok) {
      switch (response.status) {
        case 401:
          throw new Error("認証が必要です");
        case 404:
          throw new Error("データが見つかりません");
        case 429:
          throw new Error("リクエスト制限を超えました");
        default:
          throw new Error(`エラー: ${response.status}`);
      }
    }

    return await response.json();
  } catch (error) {
    // ネットワークエラーなど
    if (error.name === "TypeError") {
      console.error("ネットワークエラー");
    } else {
      console.error(error.message);
    }
    throw error;
  }
}

実践的なAPI利用例

例1: 公開APIからデータ取得

// 無料の練習用API: JSONPlaceholder
async function fetchPosts() {
  const response = await fetch(
    "https://jsonplaceholder.typicode.com/posts"
  );
  const posts = await response.json();

  // 最初の5件だけ表示
  posts.slice(0, 5).forEach(post => {
    console.log(`[${post.id}] ${post.title}`);
  });

  return posts;
}

// 特定のIDの投稿を取得
async function fetchPostById(id) {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/posts/${id}`
  );
  return await response.json();
}

// 実行例
fetchPostById(1).then(post => {
  console.log(post.title);
  console.log(post.body);
});

例2: 認証付きAPIリクエスト

// 認証トークンを使ったリクエスト
async function fetchProtectedData(token) {
  const response = await fetch("https://api.example.com/protected", {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json",
    },
  });

  if (response.status === 401) {
    // トークン期限切れなどの処理
    throw new Error("認証が必要です。再ログインしてください。");
  }

  return await response.json();
}

// ログイン処理の例
async function login(email, password) {
  const response = await fetch("https://api.example.com/login", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email, password }),
  });

  if (!response.ok) {
    throw new Error("ログインに失敗しました");
  }

  const { token } = await response.json();
  // トークンを保存
  localStorage.setItem("authToken", token);
  return token;
}

例3: API呼び出しをラップするクラス

class ApiClient {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
  }

  async request(endpoint, options = {}) {
    const url = `${this.baseUrl}${endpoint}`;

    const config = {
      headers: {
        "Content-Type": "application/json",
        ...options.headers,
      },
      ...options,
    };

    const response = await fetch(url, config);

    if (!response.ok) {
      const error = await response.json().catch(() => ({}));
      throw new Error(error.message || "APIエラー");
    }

    return response.json();
  }

  get(endpoint) {
    return this.request(endpoint);
  }

  post(endpoint, data) {
    return this.request(endpoint, {
      method: "POST",
      body: JSON.stringify(data),
    });
  }

  put(endpoint, data) {
    return this.request(endpoint, {
      method: "PUT",
      body: JSON.stringify(data),
    });
  }

  delete(endpoint) {
    return this.request(endpoint, { method: "DELETE" });
  }
}

// 使用例
const api = new ApiClient("https://api.example.com");

// ユーザー一覧取得
const users = await api.get("/users");

// ユーザー作成
const newUser = await api.post("/users", { name: "田中" });

API利用のベストプラクティス

まとめ

Web APIを使いこなすことで、天気情報、地図、決済、AIなど様々な機能を自分のアプリケーションに組み込めるようになります。まずは無料で使えるJSONPlaceholderなどの練習用APIで基本を学び、徐々に実際のサービスのAPIを使ってみましょう。fetchの基本をマスターすれば、ほとんどのWeb APIを扱えるようになります。