Featured image of post REST APIエンドポイント設計のベストプラクティス Featured image of post REST APIエンドポイント設計のベストプラクティス
API

REST APIエンドポイント設計のベストプラクティス

REST APIエンドポイント設計のベストプラクティスを徹底解説。リソース指向の命名規則、適切なHTTPステータスコードの選択、バージョン管理戦略、フィルタリングやページネーションの実装方針など、クリーンで保守しやすいAPI設計の基準を紹介します。

English
  1. ホーム
  2. web
  3. REST APIエンドポイント設計のベストプラクティス

はじめに

Webシステムやフロントエンド・バックエンドの分離開発において、API設計の美しさと一貫性 は、プロジェクトの生産性を左右する極めて重要な要素です。

一貫性のないエンドポイント名（URL）、不適切なHTTPメソッドの利用、あるいはすべて 200 OK で返されるエラーレスポンスなどは、フロントエンド開発者を混乱させ、余計なバグやドキュメント確認の手間を増やします。

本記事では、長期間にわたって利用・拡張しやすく、誰が見ても直感的に理解できる REST API設計のベストプラクティス を分かりやすく整理します。

1. 原則1: リソース指向のURL設計（名詞を使う）

REST APIの基本は「URIは操作対象の**リソース（名詞）を表し、操作自体はHTTPメソッド（動詞）**で表現する」という設計原則です。

避けるべき設計（動詞がURLに含まれている）

  • POST /getUsers (ユーザー取得)
  • POST /deletePost?id=123 (記事削除)
  • POST /create_comment (コメント作成)

URLの中に「get」「delete」「create」などのアクション（動詞）を含めてしまうと、エンドポイントが無秩序に増え、ルールが複雑化します。

改善された設計

リソース（名詞）の複数形を基本のURL構造とし、HTTPメソッドでアクションを決定します。

リソースに対する操作HTTPメソッドエンドポイント（URL）
ユーザー一覧の取得GET/users
特定のユーザー情報の取得GET/users/{id}
新規ユーザーの登録POST/users
ユーザー情報の更新PUT または PATCH/users/{id}
ユーザーの削除DELETE/users/{id}
  • 名詞の複数形を使う: 統一感を持たせるため、リソース名は原則として複数形（/users、/posts）で統一します。

2. 原則2: HTTPメソッドの正しい使い分け（冪等性の確保）

リソースの変更処理においては、PUT と PATCH の違いや、APIの「冪等性（べきとうせい：Idempotency）」を意識することが重要です。

  • PUT (置き換え): 指定したリソース全体を、送信したデータで完全に置き換えます。何度実行しても結果が変わらないため、冪等です。
  • PATCH (部分更新): 指定したリソースの一部のプロパティのみを書き換えます。
  • POST (新規作成): 実行するたびに新しいリソースが追加で作成されるため、冪等ではありません（2回リクエストを送ると2個レコードが作成されます）。

APIを呼び出すクライアント側が「再試行しても安全か」を判断できるよう、メソッドのセマンティクスは厳格に守りましょう。

3. 原則3: 適切なHTTPステータスコードの返却

APIの処理結果は、レスポンスボディの中身だけでなく、HTTPヘッダーのステータスコードで正確に表現します。

避けるべき設計（「200 OK」ですべてを返す）

ステータスコードは 200 を返しつつ、JSONボディの中でエラーコードを返す設計はアンチパターンです。

  • Bad レスポンス: 200 OK
    {
  "status": "error",
  "errorCode": 404,
  "message": "User not found"
}

採用すべき代表的なステータスコード

  • 200 OK: データの取得や更新が正常に完了した。
  • 201 Created: POST によるリソースの新規作成が正常に完了した。
  • 204 No Content: DELETE などの処理が正常に完了し、返すボディがない。
  • 400 Bad Request: クライアントが送信したパラメータのバリデーションエラーなど。
  • 401 Unauthorized: 認証トークンが無効、または未設定。
  • 403 Forbidden: 認証はされているが、そのリソースに対するアクセス権限がない。
  • 404 Not Found: 指定されたリソース（IDなど）が存在しない。
  • 500 Internal Server Error: サーバー内部のプログラムエラーやデータベース障害。

4. 原則4: フィルタリング・ソート・ページの設計

リソース一覧（例: /posts）から条件に合うデータを絞り込む場合は、URLの階層を増やすのではなく、クエリパラメータ（Query Parameters） を使用します。

良いパラメータ設計の例

  • フィルタリング: GET /posts?category=tech (カテゴリがtechの記事のみ)
  • ソート（並び替え）: GET /posts?sort=-createdAt (作成日の降順。マイナス記号で降順を表現するのが一般的)
  • ページネーション（分割表示）: GET /posts?page=2&limit=20 (2ページ目のデータを20件)

5. 原則5: APIのバージョン管理

仕様変更によるフロントエンドの破壊を防ぐため、APIには必ずバージョン管理（Versioning）を導入します。最も一般的なのは、URLの先頭にバージョンを含める方法です。

  • URLによる管理: /api/v1/users

新しい仕様のAPI（v2）をリリースしても、既存のクライアントが動いているv1を壊さずに並行稼働させることができます。

まとめ

クリーンなREST API設計は、チームの共通言語として開発をスムーズにします。

  1. URIには名詞の複数形を用い、動詞はHTTPメソッドで表現する
  2. 処理成否は適切なHTTPステータスコード（201, 400, 403, 404など）で伝える
  3. パラメータの絞り込みにはクエリストリングを使い、エンドポイントを無駄に増やさない

美しいAPI設計を心がけ、長期的にメンテナンスしやすいシステムを構築していきましょう。

© 2022 - 2026 たかおの解説