はじめに

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 を
👉 現実のコードに落とし込む
フェーズです。