APIファーストなシステム設計

はじめに

私たちの学習管理システムは、APIファーストの設計思想で構築されています。フロントエンドとバックエンドを完全に分離することで、AI開発との相性が非常に良くなりました。

APIファーストとは

【従来の設計】
サーバーがHTMLを生成して返す
→ フロントとバックが密結合

【APIファースト設計】
サーバーはJSONデータのみ返す
→ フロントとバックが疎結合

クライアント ←→ API ←→ データベース
   (HTML/JS)     (JSON)    (SQL)

APIファーストのメリット

1. 役割の明確化

【バックエンド】
- データの保存・取得
- ビジネスロジック
- 認証・認可

【フロントエンド】
- 画面表示
- ユーザー操作の処理
- API呼び出し

2. 独立した開発

フロントエンドとバックエンドを別々に開発できます。APIの仕様さえ決まれば、並行して作業可能です。

3. AI開発との相性

【AIへの指示が明確になる】

「ユーザー一覧を返すAPIを実装して」
→ エンドポイント、リクエスト、レスポンスが明確

「ユーザー一覧画面を作って」
→ どのAPIを呼ぶか、どう表示するかが明確

API設計の基本

RESTful設計

【リソース指向のURL設計】
GET    /api/users          ユーザー一覧取得
GET    /api/users/:id      ユーザー詳細取得
POST   /api/users          ユーザー作成
PUT    /api/users/:id      ユーザー更新
DELETE /api/users/:id      ユーザー削除

レスポンス形式の統一

【成功時】
{
    "success": true,
    "data": { ... }
}

【エラー時】
{
    "success": false,
    "error": {
        "code": "ERROR_CODE",
        "message": "エラーメッセージ"
    }
}

実装例

バックエンド（Express）

// ユーザー一覧API
app.get('/api/users', async (req, res) => {
    const users = await db.all(
        'SELECT user_id, email FROM users'
    );
    res.json({ success: true, data: users });
});

フロントエンド（JavaScript）

// ユーザー一覧の取得と表示
async function load_users() {
    const users = await APIClient.get('/api/users');
    render_user_list(users);
}

APIドキュメントの重要性

## GET /api/users

### 概要
登録済みユーザーの一覧を取得

### リクエスト
パラメータなし

### レスポンス
| フィールド | 型 | 説明 |
|-----------|-----|------|
| user_id | integer | ユーザーID |
| email | string | メールアドレス |

### エラー
| コード | 説明 |
|--------|------|
| AUTH_REQUIRED | 認証が必要 |

まとめ

APIファースト設計は、AI開発の基盤として最適です。明確なインターフェースがあることで、AIへの指示も明確になり、品質の高いシステムを構築できます。

---

次回：「タイムゾーン問題の落とし穴」