はじめに
Day18 までで、
✅ リクエスト / レスポンスの基礎
✅ 認証（JWT）
✅ セキュリティ（CSRF / Rate Limit）
という API 開発の土台 が完成しました。
ここからは
👉 実際に動くアプリを作るフェーズ
に入ります。
ただし、いきなりコードは書きません。
今日のゴール
・なぜ API 仕様書が必要か理解する
・SPA 用 API の設計方法を知る
・最低限必要なエンドポイントを定義する
・「迷わない開発」の土台を作る
いきなり実装してはいけない理由
ありがちな失敗例👇
・URL が場当たり的
・レスポンス形式がバラバラ
・フロントとバックで認識ズレ
・後から修正地獄 😇
👉 仕様を決めてから書く だけで防げます。
API 仕様書とは？
API 仕様書とは、
「どんなリクエストを送ると、何が返ってくるか」
を明文化した設計図
完璧でなくて OK。
まずは一覧で十分 です。
今回作るアプリ（前提）
シンプルな ミニ投稿アプリ を想定します。
機能
・ユーザー登録 / ログイン
・投稿の CRUD
・認証必須
・SPA（React想定）
エンドポイント一覧（最重要）
認証系
| メソッド | URL | 説明 | 認証 |
|---|---|---|---|
| POST | /api/register | ユーザー登録 | 不要 |
| POST | /api/login | ログイン | 不要 |
| GET | /api/me | 自分情報取得 | 必須 |
投稿系
| メソッド | URL | 説明 | 認証 |
|---|---|---|---|
| GET | /api/posts | 投稿一覧 | 必須 |
| GET | /api/posts/{id} | 投稿詳細 | 必須 |
| POST | /api/posts | 投稿作成 | 必須 |
| PUT | /api/posts/{id} | 投稿更新 | 必須 |
| DELETE | /api/posts/{id} | 投稿削除 | 必須 |
リクエスト仕様例
投稿作成
POST /api/posts
Authorization: Bearer xxx
Content-Type: application/json
{
"title": "はじめての投稿",
"body": "本文です"
}
レスポンス仕様例（成功）
{
"status": "success",
"data": {
"id": 1,
"title": "はじめての投稿",
"body": "本文です",
"user_id": 1
}
}
レスポンス仕様例（失敗）
{
"status": "error",
"message": "バリデーションエラー"
}
レスポンス形式を揃える理由
・フロント実装が楽
・エラーハンドリングが共通化
・保守性が上がる
👉 status / data / message
を基本形にすると安定します。
フロントとのやり取りを想像する
if (response.status === 'success') {
setPosts(response.data);
} else {
showError(response.message);
}
👉 API が親切だとフロントが幸せ
認証の前提も明記する
・Authorization ヘッダー必須
・JWT Bearer Token 使用
・未認証時は 401
これを決めておくだけで
「なんで動かない？」
が激減します。
仕様書はどこに書く？
・README.md
・Notion
・Google Docs
・Swagger（余裕があれば）
👉 最初は Markdown で十分
今日のポイント
・API 設計は実装より重要
・エンドポイント一覧が最優先
・レスポンス形式を統一
・認証条件を明確にする
・SPA 開発が一気に楽になる
今日のまとめ
・API 仕様書は「設計図」
・完璧でなくていい
・一覧と形式を決めるだけでOK
・実装前に迷いを消すのが目的
次回 Day20
いよいよコードを書き始めます。」
Day20 — ユーザー登録API・ログインAPIをLaravelで実装
設計した API を
👉 現実のコードに落とし込む
フェーズです。