第21回: REST設計の基本 — 「直感的に使えるAPI」はURLとメソッドの選び方で決まる

(Updated: )
1 min read

章: 第3章: RESTful API設計

/getUser?id=1 と /deletePost?id=5 —— これがなぜ「良くない」のか

URLにアクション名を含めるAPI設計は、慣れれば作れても「APIを使う側」にとっては覚えるルールが増えるだけです。

RESTはリソース（データの実体）をURLで表現し、操作はHTTPメソッド（GET/POST/PUT/DELETE等）で区別する設計スタイルです。一貫したルールに沿うだけで、誰でも直感的に使えるAPIになります。

REST設計の基本実装


# リソース設計の例
GET    /posts        # 一覧取得
POST   /posts        # 新規作成
GET    /posts/{id}   # 1件取得
PUT    /posts/{id}   # 全フィールド更新
PATCH  /posts/{id}   # 一部フィールド更新
DELETE /posts/{id}   # 削除

# ネストリソース
GET    /users/{id}/posts   # そのユーザーの記事一覧

良くないAPI設計 vs RESTful設計

操作 NGパターン RESTfulパターン
ユーザー取得 GET /getUser?id=1 GET /users/1
投稿作成 POST /createPost POST /posts
投稿削除 GET /deletePost?id=5 DELETE /posts/5
状態更新 POST /updateStatus PATCH /posts/5

チェックポイント: URLには「名詞（リソース名）」のみを使い、「動詞（アクション）」はHTTPメソッドで表現するのがRESTの核心です。

HTTPメソッドの使い分け

メソッド 用途 冪等性
GET データの取得 あり（何度呼んでも同じ）
POST データの作成 なし（毎回新規作成）
PUT 全フィールドの更新 あり
PATCH 一部フィールドの更新 あり
DELETE データの削除 あり

チェックポイント: GETリクエストはDBに副作用を与えてはいけません。GET /posts/delete?id=1 のようなGETで削除する設計はセキュリティリスク（CSRF）にもなります。

まとめ & 次のステップ

  • RESTはリソースをURLで表現し、操作をHTTPメソッドで区別する設計スタイル
  • URLには名詞のみを使い、動詞はメソッドで表現する
  • GETは副作用を持たず、冪等性の考慮がAPI設計の品質を決める

次回はJSONレスポンス設計を学びます。成功・エラーの構造を統一して、フロントエンドが扱いやすいAPIを作る方法です。

Related Articles