APIという架け橋

APIとは何か

APIは “Application Programming Interface” の略。ソフトウェア同士が会話するための「窓口」だ。

「APIはレストランのウェイター。お客さん（フロントエンド）が注文（リクエスト）を出し、キッチン（サーバー）から料理（レスポンス）を受け取る。直接キッチンに入る必要はない。」——Yuki

なぜAPIが必要か

ShimaLinkの現状の問題を整理しよう。

【Before: APIなし】
フロントエンド → 直接JSONファイルを読み書き
問題: 同時アクセスで壊れる、データ形式がバラバラ、セキュリティなし

【After: APIあり】
フロントエンド → API → データ保存
利点: ルールが統一、データの整合性、セキュリティ

Web APIの基本構造

クライアント                    サーバー
(ブラウザ)                    (バックエンド)
    |                            |
    |   HTTPリクエスト            |
    | =========================> |
    |   GET /api/clients         |
    |                            |
    |   HTTPレスポンス            |
    | <========================= |
    |   { "data": [...] }        |
    |                            |

REST API

REST（Representational State Transfer）は、Web APIの設計スタイルの一つです。

RESTの原則

URLの設計例

# リソース: クライアント
/api/clients              → クライアント全体
/api/clients/1            → ID=1のクライアント
/api/clients/1/reservations → ID=1の予約一覧

# リソース: 予約
/api/reservations         → 予約全体
/api/reservations/42      → ID=42の予約

APIの種類

ポイント: REST APIが最も広く使われている形式。まずはRESTをしっかり理解しよう。ShimaLinkのAPIもREST形式で作ります。

HTTPメソッド — GET / POST / PUT / DELETE

REST APIでは、HTTPメソッドでデータに対する操作の種類を表す。これはCRUD（作成・読み取り・更新・削除）と対応している。

「HTTPメソッドは”動詞”。URLが”名詞”。この2つで何をしたいかが分かる。」——Yuki

4つの基本メソッド

GET — データを取得する

GET /api/clients HTTP/1.1
Host: api.shimalink.com

---
レスポンス:
HTTP/1.1 200 OK
Content-Type: application/json

[
  { "id": 1, "name": "海風テラス", "category": "カフェ" },
  { "id": 2, "name": "首里そば太郎", "category": "飲食" }
]

// fetchでGETリクエスト（デフォルトはGET）
const response = await fetch("/api/clients");
const clients = await response.json();

POST — 新規作成

POST /api/clients HTTP/1.1
Content-Type: application/json

{ "name": "やんばるキッチン", "category": "飲食" }

---
レスポンス:
HTTP/1.1 201 Created

{ "id": 6, "name": "やんばるキッチン", "category": "飲食" }

const newClient = { name: "やんばるキッチン", category: "飲食" };

const response = await fetch("/api/clients", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(newClient)
});

const created = await response.json();
console.log(created.id); // サーバーが割り当てたID

PUT — データを更新

PUT /api/clients/1 HTTP/1.1
Content-Type: application/json

{ "name": "海風テラス", "category": "カフェ", "visits": 1500 }

---
レスポンス:
HTTP/1.1 200 OK

{ "id": 1, "name": "海風テラス", "category": "カフェ", "visits": 1500 }

const updated = {
  name: "海風テラス",
  category: "カフェ",
  visits: 1500
};

const response = await fetch("/api/clients/1", {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(updated)
});

DELETE — データを削除

DELETE /api/clients/3 HTTP/1.1

---
レスポンス:
HTTP/1.1 204 No Content

const response = await fetch("/api/clients/3", {
  method: "DELETE"
});

if (response.ok) {
  console.log("削除成功");
}

ステータスコード

メソッドの特性

「冪等（べきとう）」とは、同じリクエストを何度送っても結果が同じという意味。GETは何度取得しても同じデータ。PUTは何度更新しても同じ状態。POSTは送るたびに新しいデータが作られる。

ポイント: URLは「何に対して」、HTTPメソッドは「何をするか」を表す。DELETE /api/clients/3 は「ID 3のクライアントを削除する」と読める。

JSON — データの共通言語

APIでやり取りするデータのフォーマットには、JSON（JavaScript Object Notation） が使われる。

「JSONは”データの共通言語”。JavaScript出身だけど、今やどんな言語でも読み書きできる。」——Yuki

JSONとは

JSON はテキストベースのデータ形式で、人間にも機械にも読みやすい。

{
  "name": "海風テラス",
  "owner": "Mika",
  "category": "カフェ",
  "monthlyVisits": 1250,
  "isActive": true,
  "tags": ["オーシャンビュー", "テラス席", "ペットOK"],
  "address": {
    "prefecture": "沖縄県",
    "city": "北谷町",
    "detail": "美浜1-2-3"
  }
}

JSONのルール

JSONで使えるデータ型

{
  "string": "文字列",
  "number": 42,
  "float": 3.14,
  "boolean": true,
  "null": null,
  "array": [1, 2, 3],
  "object": { "key": "value" }
}

注意: 関数、undefined、Date オブジェクトなどはJSONに含められません。

JavaScriptでのJSON操作

// オブジェクト → JSON文字列
const client = { name: "海風テラス", visits: 1250 };
const jsonString = JSON.stringify(client);
// '{"name":"海風テラス","visits":1250}'

// JSON文字列 → オブジェクト
const parsed = JSON.parse(jsonString);
// { name: "海風テラス", visits: 1250 }

// 整形出力（デバッグ用）
const pretty = JSON.stringify(client, null, 2);
// {
//   "name": "海風テラス",
//   "visits": 1250
// }

APIでの使い方

リクエスト（送信側）

// POSTでJSONデータを送信
const response = await fetch("/api/clients", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"  // JSONであることを宣言
  },
  body: JSON.stringify({                // オブジェクトをJSON文字列に変換
    name: "やんばるキッチン",
    category: "飲食"
  })
});

レスポンス（受信側）

// レスポンスのJSONをパース
const response = await fetch("/api/clients");
const data = await response.json();  // JSON → オブジェクト

// TypeScriptで型をつける
interface Client {
  id: number;
  name: string;
  category: string;
}

const clients: Client[] = await response.json();

ShimaLink APIのレスポンス設計

統一されたレスポンス形式を定義しよう。

// 成功レスポンス
interface ApiSuccess<T> {
  success: true;
  data: T;
}

// エラーレスポンス
interface ApiError {
  success: false;
  error: {
    code: string;
    message: string;
  };
}

type ApiResponse<T> = ApiSuccess<T> | ApiError;

// 成功時
{
  "success": true,
  "data": [
    { "id": 1, "name": "海風テラス", "category": "カフェ" }
  ]
}

// エラー時
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "クライアントが見つかりません"
  }
}

ポイント: APIのレスポンス形式を統一することで、フロントエンド側のエラーハンドリングがシンプルになります。success フラグで成功/失敗を判定する設計は非常に一般的です。

シンプルなAPIを構築する

学んだ知識を統合して、ShimaLink用のAPIを設計・実装してみよう。ここではfetch APIを使ってフロントエンドからAPIを呼び出す実装に焦点を当てる。

「まずはAPIの”使い方”を完璧にしよう。作る側は次のステップだ。」——Yuki

ShimaLink APIの設計

まず、必要なエンドポイントを洗い出す。

ShimaLink API エンドポイント一覧
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GET    /api/clients           クライアント一覧取得
GET    /api/clients/:id       特定のクライアント取得
POST   /api/clients           新規クライアント登録
PUT    /api/clients/:id       クライアント情報更新
DELETE /api/clients/:id       クライアント削除

GET    /api/clients/:id/reservations  予約一覧取得
POST   /api/clients/:id/reservations  予約追加

型定義

// types.ts
interface Client {
  id: number;
  name: string;
  owner: string;
  category: "カフェ" | "飲食" | "花屋" | "雑貨" | "その他";
  monthlyVisits: number;
  isActive: boolean;
  createdAt: string;
}

interface Reservation {
  id: number;
  clientId: number;
  guestName: string;
  date: string;
  partySize: number;
  status: "confirmed" | "pending" | "cancelled";
}

interface ApiResponse<T> {
  success: boolean;
  data: T;
  message?: string;
}

APIクライアント関数の実装

// api.ts — ShimaLink APIクライアント

const BASE_URL = "/api";

// 共通のfetch関数
async function apiRequest<T>(
  endpoint: string,
  options?: RequestInit
): Promise<ApiResponse<T>> {
  const response = await fetch(`${BASE_URL}${endpoint}`, {
    headers: {
      "Content-Type": "application/json",
    },
    ...options,
  });

  if (!response.ok) {
    throw new Error(`API Error: ${response.status}`);
  }

  return response.json();
}

CRUD操作の実装

// READ: クライアント一覧を取得
async function getClients(): Promise<Client[]> {
  const result = await apiRequest<Client[]>("/clients");
  return result.data;
}

// READ: 特定のクライアントを取得
async function getClient(id: number): Promise<Client> {
  const result = await apiRequest<Client>(`/clients/${id}`);
  return result.data;
}

// CREATE: 新規クライアント登録
async function createClient(
  client: Omit<Client, "id" | "createdAt">
): Promise<Client> {
  const result = await apiRequest<Client>("/clients", {
    method: "POST",
    body: JSON.stringify(client),
  });
  return result.data;
}

// UPDATE: クライアント情報更新
async function updateClient(
  id: number,
  updates: Partial<Client>
): Promise<Client> {
  const result = await apiRequest<Client>(`/clients/${id}`, {
    method: "PUT",
    body: JSON.stringify(updates),
  });
  return result.data;
}

// DELETE: クライアント削除
async function deleteClient(id: number): Promise<void> {
  await apiRequest<void>(`/clients/${id}`, {
    method: "DELETE",
  });
}

ダッシュボードでの使用例

// dashboard.ts — ダッシュボードの表示ロジック

async function renderDashboard() {
  try {
    // クライアント一覧を取得
    const clients = await getClients();

    // アクティブなクライアントだけ表示
    const activeClients = clients.filter(c => c.isActive);

    // HTML生成
    const container = document.getElementById("client-list");
    if (!container) return;

    container.innerHTML = activeClients
      .map(client => `
        <div class="client-card" data-id="${client.id}">
          <h3>${client.name}</h3>
          <p>${client.category} | ${client.owner}</p>
          <p>月間アクセス: ${client.monthlyVisits.toLocaleString()}</p>
          <button onclick="handleEdit(${client.id})">編集</button>
          <button onclick="handleDelete(${client.id})">削除</button>
        </div>
      `)
      .join("");

  } catch (error) {
    console.error("ダッシュボードの読み込みに失敗:", error);
    showErrorMessage("データの取得に失敗しました。再度お試しください。");
  }
}

// 新規クライアント追加フォームの処理
async function handleCreateClient(form: HTMLFormElement) {
  const formData = new FormData(form);

  const newClient = {
    name: formData.get("name") as string,
    owner: formData.get("owner") as string,
    category: formData.get("category") as Client["category"],
    monthlyVisits: 0,
    isActive: true,
  };

  try {
    await createClient(newClient);
    await renderDashboard(); // 一覧を再描画
    form.reset();
  } catch (error) {
    console.error("クライアント登録に失敗:", error);
  }
}

エラーハンドリングのパターン

async function safeApiCall<T>(
  apiCall: () => Promise<T>,
  fallback: T
): Promise<T> {
  try {
    return await apiCall();
  } catch (error) {
    if (error instanceof Error) {
      console.error(`API Error: ${error.message}`);
    }
    return fallback;
  }
}

// 使用例: エラー時は空配列を返す
const clients = await safeApiCall(
  () => getClients(),
  []
);

ポイント: API呼び出しは必ず失敗する可能性がある（ネットワーク障害、サーバーエラーなど）。try/catchで適切にエラーを処理し、ユーザーにフィードバックを返すことが重要です。

GET    /api/clients          → クライアント一覧
GET    /api/clients/:id      → 特定のクライアント
POST   /api/clients          → 新規クライアント登録
PUT    /api/clients/:id      → クライアント情報更新
DELETE /api/clients/:id      → クライアント削除