🔌 バックエンド基礎講座【第二回】API設計の基礎！REST・HTTPメソッド・ステータスコード・エンドポイント設計

Posted at 2026-07-08

1. 👋 はじめに

前回はバックエンドの基本概念（サーバー・クライアント・リクエスト・レスポンス）を学びました。

今回は API設計の基礎 を解説します！

APIはバックエンドの「窓口」です。
フロントエンドとバックエンドがどうやってデータをやり取りするか、
その設計ルールを理解しましょう。

この記事を読めば：

✅ APIとは何かがわかる
✅ RESTfulな設計とは何かがわかる
✅ HTTPメソッドの使い分けがわかる
✅ 良いエンドポイント設計の考え方がわかる

2.🔌 APIとは？

一言で言うと

API（Application Programming Interface）とは「アプリケーション同士が会話するための窓口」です。

レストランで例えると

🍽️ レストランの注文システムに例えると：

お客様（フロントエンド）
    ↓
メニュー表・注文用紙（API）← 決まった形式で注文する
    ↓
厨房（バックエンド）

APIがあることで：
  ✅ お客様は厨房の中の仕組みを知らなくていい
  ✅ 厨房はお客様の画面の作り方を知らなくていい
  ✅ お互いに「APIという窓口」だけを通じてやり取りする

APIがなかったら？

❌ APIなし：
  フロントエンドが直接DBにアクセス
  → セキュリティ上の問題が山積み
  → フロントエンドとバックエンドが密結合になる

✅ APIあり：
  フロントエンド → API → バックエンド → DB
  → バックエンドがデータを安全に管理できる
  → フロントエンドの実装が変わってもAPIが同じなら問題なし

3. 📋 RESTfulとは？

RESTとは？

REST（Representational State Transfer）とは「WebAPIの設計スタイルの1つ」です。
厳密な仕様ではなく「こう設計しましょう」という考え方・原則です。
RESTの原則に従って設計されたAPIを RESTful API と呼びます。

RESTfulの6つの原則

原則	説明	例
🎯 統一インターフェース	一貫したURLルールとHTTPメソッドを使う	`GET /users`・`POST /users`
📦 ステートレス	サーバーはリクエストの状態を保持しない	各リクエストに認証情報を含める
🖥️ クライアント・サーバー分離	フロントとバックを明確に分ける	ReactアプリとPython APIを別々に開発
💾 キャッシュ可能	レスポンスをキャッシュできるか明示する	変わらないデータはキャッシュして高速化
🔗 階層型システム	中間サーバー（プロキシ等）を挟める	CDN・ロードバランサーを透過的に使える
📩 コードオンデマンド（任意）	サーバーからクライアントに実行可能なコードを送れる	サーバーからJavaScriptを送って実行させる

💡 コードオンデマンドは6つの中で唯一「任意（オプション）」の原則です。
現代のWebアプリ（ReactやVueなど）ではすでに自然に使われている考え方ですが、意識して設計することは少ないです。

実務では「統一インターフェース・ステートレス・クライアントサーバー分離」の3つを意識するだけで十分きれいなAPIが設計できます。

4. 🛠️ HTTPメソッドの使い分け

5つの主要メソッド

HTTPメソッドは「何をしたいか」を表す動詞です。
URLは「どのリソースか」を表す名詞なので、
メソッド + URL で「〇〇に対して△△をする」が表現できます。

メソッド	意味	使う場面	例
`GET`	取得	データを読み取る	ユーザー一覧を取得
`POST`	作成	新しいデータを作る	新規ユーザーを登録
`PUT`	更新（全体）	データ全体を置き換える	ユーザー情報をすべて更新
`PATCH`	更新（一部）	データの一部だけ変更	メールアドレスだけ変更
`DELETE`	削除	データを削除する	ユーザーを削除

CRUD と HTTPメソッドの対応

CRUD（クラッド） とはデータ操作の4つの基本操作です。

CRUD	意味	HTTPメソッド
Create	作成	`POST`
Read	読み取り	`GET`
Update	更新	`PUT` / `PATCH`
Delete	削除	`DELETE`

PUT と PATCH の違い

【ユーザー情報の例】
現在のデータ：
{
  "name": "田中太郎",
  "email": "taro@example.com",
  "age": 25
}

PUT（全体を置き換え）：
  送るデータ：{ "name": "田中花子", "email": "hanako@example.com", "age": 25 }
  → 送らなかったフィールドは削除される可能性がある
  → 必ず全フィールドを送る必要がある

PATCH（一部だけ変更）：
  送るデータ：{ "email": "hanako@example.com" }
  → 送ったフィールドだけを更新
  → 他のフィールドはそのまま残る

5. 🗺️ エンドポイント設計のベストプラクティス

エンドポイントとは？

エンドポイントとは「APIの窓口となるURL」のことです。
https://api.example.com/users のようなURLがエンドポイントです。

✅ 良いエンドポイント設計

① URLは名詞（リソース）で表現する・② 複数形を使う・③ バージョン管理をする

操作内容	❌ 悪い設計（動詞・バラバラ）	✅ 良い設計（REST・リソース指向）
ユーザー一覧の取得	`GET /getUsers`	`GET /api/v1/users`
新規ユーザーの登録	`POST /createUser`	`POST /api/v1/users`
特定ユーザーの更新	`POST /updateUser?id=123`	`PATCH /api/v1/users/123`
特定ユーザーの削除	`DELETE /deleteUser/123`	`DELETE /api/v1/users/123`

悪い設計の問題点：

URLに動詞（getUsers・createUser）が混入している

更新なのに POST を使っている（メソッドの意味が失われる）

バージョン管理がない（仕様変更時に困る）

命名が一貫していない（チームで混乱する）

④ 階層構造でリソースの関係を表現する

✅ 階層構造の例：

  /api/v1/users              ← ユーザー一覧
  /api/v1/users/123          ← ID:123のユーザー
  /api/v1/users/123/posts    ← ID:123のユーザーの投稿一覧
  /api/v1/users/123/posts/456 ← ID:123のユーザーの投稿ID:456

⑤ 小文字・ハイフン区切りを使う

❌ 悪い例：          ✅ 良い例：
  /UserProfile    →    /user-profiles
  /user_profile   →    /blog-posts
  /USERPROFILE    →    /order-items

ユーザー管理APIの設計例

【ユーザー管理APIの全エンドポイント】

GET    /api/v1/users          → ユーザー一覧を取得
POST   /api/v1/users          → 新しいユーザーを作成
GET    /api/v1/users/{id}     → 特定のユーザーを取得
PUT    /api/v1/users/{id}     → 特定のユーザーを全体更新
PATCH  /api/v1/users/{id}     → 特定のユーザーを部分更新
DELETE /api/v1/users/{id}     → 特定のユーザーを削除

【ネストの例：ユーザーの投稿】
GET    /api/v1/users/{id}/posts      → ユーザーの投稿一覧
POST   /api/v1/users/{id}/posts      → ユーザーの投稿を作成
DELETE /api/v1/users/{id}/posts/{postId} → 特定の投稿を削除

6. 📦 リクエスト・レスポンスの形式

JSONとは？

JSON（JavaScript Object Notation）とは「データの受け渡しに使う軽量なフォーマット」です。
現代のWeb APIではほぼ必ずJSONが使われます。

{
  "id": 123,
  "name": "田中太郎",
  "email": "taro@example.com",
  "age": 25,
  "isAdmin": false,
  "tags": ["エンジニア", "東京"],
  "address": {
    "city": "渋谷区",
    "prefecture": "東京都"
  }
}

リクエスト・レスポンスの実例

新しいユーザーを作成する（POST /users）：

【リクエスト】
POST /api/v1/users
Content-Type: application/json  ← 「これからJSON形式のデータを送りますよ」という合図！
                                   これがないとサーバーがデータの形式を判断できない

{
  "name": "田中太郎",
  "email": "taro@example.com",
  "password": "securePassword123"
}

【レスポンス】201 Created
Content-Type: application/json  ← 「JSONで返しますよ」という合図

{
  "id": 123,
  "name": "田中太郎",
  "email": "taro@example.com",
  "createdAt": "2026-01-01T00:00:00Z"
}

※ パスワードはレスポンスに含めない！（セキュリティ上の鉄則）

存在しないユーザーを取得する（GET /users/999）：

【リクエスト】
GET /api/v1/users/999

【レスポンス】404 Not Found
{
  "error": "User not found",
  "message": "ID:999のユーザーは存在しません",
  "statusCode": 404
}

7. 🔍 APIの種類：REST以外も知っておこう

ここまで学んできたREST APIの他にも、用途に応じたAPI通信方式があります。
今は「こんなものがある」程度に知っておくだけでOKです！

種類	特徴	💡 どんな時に使う？
GraphQL	必要なデータだけを狙い撃ちで取得できる	画面ごとに欲しいデータが細かく変わる複雑なアプリ
gRPC	爆速・型安全（データの通信量が少ない）	サーバー同士が超高速で通信し合う裏方のシステム
WebSocket	繋がりっぱなしで双方向通信ができる	チャット・オンラインゲーム・リアルタイム通知

💡 まずはREST APIを完全に理解することが最優先です！
GraphQL・gRPCはREST APIの概念を理解してから学ぶと非常にスムーズです。

8. 🎯 まとめ

概念	一言で言うと
🔌 API	アプリ同士が会話するための窓口
📋 REST	WebAPI設計の考え方・原則
🛠️ HTTPメソッド	GET・POST・PUT・PATCH・DELETE
🗂️ CRUD	Create・Read・Update・Delete
🗺️ エンドポイント	APIの窓口となるURL
📦 JSON	データの受け渡しに使うフォーマット

良いAPI設計の3原則

① URLは名詞（リソース）で表現する
  → /getUsers ❌  /users ✅

② HTTPメソッドで操作を表現する
  → GET=取得・POST=作成・PUT/PATCH=更新・DELETE=削除

③ 一貫性を保つ
  → チーム全体で同じルールを使う

良いAPI設計とは「使う人が迷わない設計」です。
URLを見るだけで「何ができるか」がわかるAPIを目指しましょう💪

次回は データベースの基礎 を解説します！
テーブル設計・SQLの基本・リレーションの考え方を学びます🌟

💬 質問や感想があれば、コメント欄でお気軽にどうぞ!
👍 役に立ったら、いいね&ストックをお願いします!
🎓 ここまで読んでくださって、本当にありがとうございました!

🔗 シリーズ記事

【第一回】バックエンドとは何か・サーバーの基本
【第二回】API設計の基礎（この記事）
【第三回】データベースの基礎（近日公開）
【第四回】認証・認可の基礎（近日公開）
【第五回】バックエンド設計の実践（近日公開）
【第六回】まとめ・デプロイ・次のステップ（近日公開）

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up