apiaryでAPIモック作成

• 日程: Day 4 / セッション 02
• 時間: 9:30-10:00
• 形式: 実習
• ゴール: 自チームの主要情報モデル1つに対するREST APIモック（GET/POST/PUT/DELETE）をapiaryで作成し、curl またはブラウザで実際に応答を取得できる
• 学習形式: ハンズオン実習（AIペアプログラミング）

前のセッションで「APIとUIを分離する」「API仕様を先に固める」という方針を確認しました。では具体的にどう「先に固める」のか。仕様書をWord文書で書く？それともいきなりサーバコードを書く？

答えはどちらでもありません。仕様書を書くと同時にモックサーバが立ち上がるツールを使います。それがapiaryです。

apiaryでは「API Blueprint」というMarkdown風の記法でAPIを書きます。すると同じ内容から、

• 見やすい仕様書ページ
• リクエストすれば応答を返すモックサーバURL

の2つが自動生成されます。UI担当はそのURLを叩けば、APIの実装を待たずに開発を進められます。Day 1で習った「動いた！」の小さな成功体験を、APIで再現する時間です。

API Blueprintは、Markdownを拡張した記法です。次の構造を覚えれば最初は十分です。

FORMAT: 1A
HOST: https://example.com/

# レシピ管理API

レシピ情報を管理するシンプルなREST API。

## レシピ一覧 [/recipes]

### 一覧取得 [GET]
+ Response 200 (application/json)
    + Body
            [
              { "id": 1, "title": "カレーライス", "time": 30 },
              { "id": 2, "title": "オムライス", "time": 20 }
            ]

### 新規作成 [POST]
+ Request (application/json)
    + Body
            { "title": "肉じゃが", "time": 40 }
+ Response 201 (application/json)
    + Body
            { "id": 3, "title": "肉じゃが", "time": 40 }

## レシピ詳細 [/recipes/{id}]
+ Parameters
    + id: 1 (number) - レシピのID

### 1件取得 [GET]
+ Response 200 (application/json)
    + Body
            { "id": 1, "title": "カレーライス", "time": 30, "ingredients": ["肉","じゃがいも"] }

### 更新 [PUT]
+ Request (application/json)
    + Body
            { "title": "ビーフカレー", "time": 35 }
+ Response 200 (application/json)
    + Body
            { "id": 1, "title": "ビーフカレー", "time": 35 }

### 削除 [DELETE]
+ Response 204

• # 見出し がAPI全体の名前
• ## リソース [/path] でURLを宣言
• ### メソッド [GET] でHTTPメソッドを宣言
• + Response + Request でリクエスト/レスポンスを書く
• インデント（半角スペース4つ）が崩れると認識されません

昔は「仕様書」は紙のドキュメントでした。書いた仕様と実装が乖離しても、誰も気付かない（誰も読まない）のが日常茶飯事。API Blueprintのように「書いたら即モックが動く」「テストツールに食わせれば仕様準拠を自動チェックできる」仕組みは、仕様を実行可能にした革命です。同じ思想を持つツールにOpenAPI（旧Swagger）、RAMLなどがあります。

モックURLは curl や fetch で呼び出すと、Blueprintに書いたレスポンス（JSON）が返ります。

1. apiary.io にサインアップしてプロジェクトを作る
2. エディタにAPI Blueprintを貼り付ける
3. 自動でモックURL（例：https://private-xxxx.apiary-mock.com/）が生成される
4. curl やブラウザ、JavaScriptのfetchでそのURLを叩く

curlで試す例：

# 一覧取得
curl https://private-xxxx.apiary-mock.com/recipes

# 新規作成
curl -X POST -H "Content-Type: application/json" \
     -d '{"title":"肉じゃが","time":40}' \
     https://private-xxxx.apiary-mock.com/recipes

JavaScriptで試す例：

// 一覧取得
fetch('https://private-xxxx.apiary-mock.com/recipes')
  .then(res => res.json())
  .then(data => console.log(data));

// 新規作成
fetch('https://private-xxxx.apiary-mock.com/recipes', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: '肉じゃが', time: 40 })
})
  .then(res => res.json())
  .then(data => console.log(data));

モックサーバはBlueprintに書いた応答をそのまま返すだけです。POSTしてもデータは保存されません。あくまで「形」を共有するための仮サーバです。本物の保存・更新は次のセッションで作ります。

ここまでの内容で疑問があれば、AIに質問してみましょう。たとえば：

• 「API Blueprintの記法でインデントが上手くいかない、書き直してくれる？」
• 「自分のチームの情報モデル『〇〇』のCRUDを、API Blueprintで書いて」
• 「apiaryでなく無料の代替ツールはある？」

自チームの主要情報モデル1つを選び、そのCRUD全て（GET一覧 / GET詳細 / POST / PUT / DELETE）をAPI Blueprintで書き、apiaryに登録してください。書けたらcurl または ブラウザでモックURLを叩き、JSON応答が返ることを確認します。

• API Blueprintのテキスト（.apibまたは.md形式でGitHubに置く）
• apiaryのモックURL
• curl実行結果のスクリーンショット または コンソール出力ログ

• 情報モデル名は複数形でURLにする（/recipes, /users, /orders）
• IDは1件取得・更新・削除のURLパスに入れる（/recipes/{id}）
• レスポンスのJSONは、Day 2で作った情報モデル定義の「属性」をそのまま使う
• 詰まったら「私のチームのモデルは〇〇で、属性は△△です。Blueprintを書いて」とAIに頼む
• インデントが崩れて読み込めない時は、AIに「インデント直して」と頼むのが速い

API Blueprintを書けば、仕様書とモックサーバが同時に手に入ります。これでUI担当は、APIの本実装を待たずに画面開発を始められます。「仕様を先に固めて並行作業する」というDay 4の核心を、たった30分で体感したことになります。

次のセッションでは、いよいよAPI本体の実装に入ります。モックで決めた「形」を、本物のロジックで動かしていきます。

• API Blueprintの「リソース」「メソッド」「リクエスト」「レスポンス」の構文を空で書けますか？
• なぜモックサーバが「並行作業」を可能にするのか説明できますか？
• 自分のチームのモデル1つについて、CRUD 5つのURL+メソッドを言えますか？

• 参考リンク: API Blueprint公式（apiblueprint.org）、apiary公式チュートリアル
• 発展課題: 同じAPIをOpenAPI（YAML/JSON）形式でも書いて、書き味の違いを比較する