モックAPIを作って動かす

• 日程: Day 4 / セッション 2
• 時間: [9:30-10:30]
• 形式: 実習
• ゴール: Day 3 の RESTful API 設計書をもとにモックAPIを作成し、ブラウザまたは curl から JSON レスポンスを取得できる（エンドポイント3本以上が応答する状態）
• 学習形式: ハンズオン実習（AIペアプログラミング）

前のセッションで、機能側＝モックAPIを先に固めると宣言しました。ここからは手を動かします。

ここで少し考えてみてください。あなたの API 設計書には「GET /expenses は支出の一覧を JSON で返す」と書いてあるはずです。この一文が「実際に叩くと JSON が返ってくるサーバ」に変わるまで、何分かかると思いますか？　半日？　1時間？

正解は、うまくいけば5分です。モックAPIツールの進化のおかげで、設計書さえあれば機能側の外形は一瞬で立ち上がります。だからこそ Day 3 で設計書を書いたのです。設計の精度が今日の速度を決める、を体感しましょう。

モックAPIとは、本物の業務ロジックやデータベースを持たず、決められた形のレスポンスだけを返す「ハリボテのAPI」です。

ハリボテというと悪く聞こえますが、映画のセットと同じで、正面（外形）が本物と同じであることに価値があります。

• UI 側から見れば、本物の API と区別がつかない
• だから UI の開発をすぐに始められる
• 後で本物の API に差し替えても、UI は接続先の変更だけで済む

これができるのは、プレゼンテーションと機能が「HTTP と JSON という契約」で分離されているからです。契約さえ守れば、中身は差し替え自由。分離の恩恵を最初に受け取るのが、このモックAPIです。

逆に、UI のコードの中に直接データを書き込む（例: HTML にダミーの表をベタ書きする）のはモックAPIではありません。それは分離を壊した「ハリボテUI」です。なぜなら、本物の API ができたときに UI を書き直すことになるからです。

• モックの価値は「外形が本物と同じ」こと。URL・メソッド・JSON の形は設計書どおりに作る
• 「機能側を先に固める」のは、契約を先に確定させるため

「モック（mock）」の原義は「あざける・まねる」です。モッキンバード（mockingbird、マネシツグミ）は他の鳥の鳴き声をまねる鳥で、小説『アラバマ物語』の原題 To Kill a Mockingbird にも登場します。ソフトウェアのモックも「本物の鳴きまね」をする存在。ちなみにテスト用語では mock・stub・fake・spy が微妙に区別されますが、実務では全部まとめて「モック」と呼ばれがちで、用語の多義性（こうもり問題！）がここにも潜んでいます。

教育要件の推奨ツールは apiary です。API Blueprint という Markdown 風の記法で設計書を書くと、クラウド上にモックサーバが立ちます。

FORMAT: 1A

# Kakeibo API

## 支出一覧 [/expenses]

### 一覧を取得 [GET]

+ Response 200 (application/json)

        [
            { "id": 1, "date": "2026-07-06", "categoryId": 1, "amount": 850, "memo": "昼食" }
        ]

設計書がそのままモックになる。デザインファーストの思想が美しいツールです。ただし、アカウント登録が必要でクラウド前提です。

本研修では、ローカルで完結する JSON Server を主の手順にします。役割は同じ「モックAPI」です。

• db.json というファイルを1つ書く
• コマンド1つで REST API が起動する
• GET だけでなく POST/PUT/DELETE も動き、db.json が実際に書き換わる

どちらを使っても「機能の外形を先に固める」という目的は同じです。時間に余裕があれば apiary も試してみてください。

家計簿システムの api/db.json の例です。Day 1 の情報定義書と Day 2 の情報モデルが、そのままデータの形になっていることを確認してください。

{
  "expenses": [
    { "id": 1, "date": "2026-07-05", "categoryId": 1, "amount": 850, "memo": "昼食のパスタ" },
    { "id": 2, "date": "2026-07-05", "categoryId": 2, "amount": 1480, "memo": "書籍" },
    { "id": 3, "date": "2026-07-06", "categoryId": 1, "amount": 620, "memo": "コーヒーとサンドイッチ" }
  ],
  "categories": [
    { "id": 1, "name": "食費" },
    { "id": 2, "name": "教養・娯楽" },
    { "id": 3, "name": "交通費" }
  ],
  "budgets": [
    { "id": 1, "month": "2026-07", "categoryId": 1, "amount": 30000 }
  ]
}

起動と確認の手順です。

# 1. 作業フォルダを作る
mkdir -p kakeibo/api && cd kakeibo/api

# 2. db.json を上の内容で作成する（エディタで作成）

# 3. JSON Server を起動する（npm があれば npx で即実行できる）
npx json-server db.json --port 3000

起動したら、別のターミナルとブラウザで確認します。

# 一覧取得（GET）
curl http://localhost:3000/expenses

# 1件取得（GET）
curl http://localhost:3000/expenses/1

# 新規登録（POST）: db.json に実際に追記される
curl -X POST http://localhost:3000/expenses \
  -H "Content-Type: application/json" \
  -d '{ "date": "2026-07-06", "categoryId": 3, "amount": 210, "memo": "バス" }'

# 更新（PUT）と削除（DELETE）
curl -X PUT http://localhost:3000/expenses/1 \
  -H "Content-Type: application/json" \
  -d '{ "date": "2026-07-05", "categoryId": 1, "amount": 900, "memo": "昼食のパスタ大盛" }'
curl -X DELETE http://localhost:3000/expenses/3

ブラウザで http://localhost:3000/expenses を開くと、同じ JSON が表示されます。ブラウザのアドレスバーは「GET リクエスト送信機」なのです。

• db.json のトップレベルのキー（expenses など）が、そのままリソース名＝URL になる
• Day 2 の状態遷移で定義した CRUD が、GET/POST/PUT/DELETE に1対1で対応する
• POST の後に db.json を開いて、データが増えていることを目で確認する。「機能が動いた」証拠

JSON の生みの親ダグラス・クロックフォードは「私は JSON を発明していない。自然界にすでに存在していたものを発見しただけだ」と語っています。JavaScript のオブジェクト記法は仕様の中に最初からあり、彼はそれに名前を付けて仕様書（たった数ページ！）を書いただけ、というわけです。2000年代初頭、XML 全盛の時代に「タグの閉じ忘れもスキーマも要らない」JSON は異端でしたが、今や Web の共通語です。シンプルなものが勝つ、という UNIX 哲学の好例です。

• 「json-server コマンドが見つからないというエラーが出た（エラー全文を貼る）。Node.js のバージョン確認から順に切り分けて」
• 「私の API 設計書はこれ（貼り付ける）。JSON Server の db.json に変換して。ただし属性名は設計書のまま変えないで」
• 「JSON Server が自動で提供してくれる機能（フィルタ、ページング、ソート）を、私の家計簿APIでの具体例つきで教えて」

1. api/db.json を作成する（15分）

   • Day 3 の API 設計書のリソースを最低2種類（例: expenses と categories）定義する
   • 各リソースに現実的なサンプルデータを3件以上入れる
2. JSON Server を起動し、動作確認する（15分）

   • ブラウザで一覧 GET を確認する
   • curl で「一覧 GET」「1件 GET」「POST」の3本以上を実行し、レスポンスを確認する
   • POST 後に db.json が書き換わったことを確認する
3. エラー解決の練習（10分）

   • わざと間違える: db.json のカンマを1つ消して起動し、エラーメッセージを AI に貼り付けて原因を説明してもらう
   • 直したら、AI の説明を自分の言葉で1行メモに残す

• 動作する api/db.json（リソース2種類以上、エンドポイント3本以上が応答）
• curl の実行結果ログ（コピペでよい）
• エラー解決メモ1行以上

• npm が未導入なら、Node.js の LTS 版をインストールする。node -v と npm -v で確認
• ポート3000が使用中なら --port 3001 に変える
• id は JSON Server が自動採番するので、POST のボディに含めなくてよい
• 属性名を英語にするか迷ったら英語を推奨。ただし情報定義書との対応表をメモに残すこと（ユビキタス言語の実践）

今回学んだことを一言でまとめると「設計書どおりの外形を持つモックAPIを立てれば、機能側は完成したのと同じ土台になる」です。

• モックの価値は外形（URL・メソッド・JSON）が本物と同じこと
• db.json のデータ構造は Day 1〜2 の情報の設計から来ている
• CRUD と HTTP メソッドは1対1で対応した

次のセッションでは、この API を UI から fetch で呼び出します。curl でやったことを、JavaScript にやらせるだけです。

• モックAPIの価値を「外形」という言葉を使って説明できますか？
• あなたの db.json のリソース名と属性は、どの成果物から来たか言えますか？
• curl で POST する場合に必要なオプションを2つ挙げられますか？

• 参考リンク: JSON Server 公式 README（npm）、API Blueprint 公式チュートリアル、MDN「HTTP リクエストメソッド」
• 発展課題: apiary に登録し、同じ API を API Blueprint で記述してモックを立て、JSON Server との違い（得意・不得意）を AI と議論する