API設計のベストプラクティス RESTful APIを中心に

使いやすい API は、それだけで開発体験を大きく左右します。RESTful API の設計には確立された原則があり、押さえるだけで一貫性と保守性が段違いになります。実務で効く基本を整理しました。

RESTful APIとは

REST は Web の仕組みに沿って API を設計する考え方です。「データ（リソース）」を URL で表し、それに対する操作を HTTP メソッドで表現します。ルールがシンプルなので、初見の開発者でも直感的に使えるのが強みです。

1. URLは"リソース（名詞）"で表す

URL に動詞を入れず、対象となるモノを名詞・複数形で表現します。

❌ /getUsers  /createUser  /deleteUser
✅ GET    /users        # 一覧取得
✅ GET    /users/1      # 個別取得
✅ POST   /users        # 作成
✅ PUT    /users/1      # 更新
✅ DELETE /users/1      # 削除

「何をするか」は URL ではなく HTTP メソッドが担います。

URL設計の細かいルール

• 階層は「所属」を表す：GET /users/1/orders（ユーザー1の注文一覧）。ただし2階層までに抑える。
• 単語区切りはケバブケース：/order-items。/orderItemsや/order_itemsは避ける。
• 末尾スラッシュは付けないで統一。/users に一本化。
• 大文字を使わない。パスは小文字のみ。
• どうしても動詞が必要な操作（検索、集計など）は /search のようなサブリソースにする。

2. HTTPメソッドを正しく使い分ける

• GET：取得（副作用なし）
• POST：新規作成
• PUT / PATCH：更新（全体 / 一部）
• DELETE：削除

PUT と PATCH の違い：PUT はリソース全体を置き換える（送らなかった項目は消える想定）、PATCH は送った項目だけ部分更新します。

冪等性（べきとうせい）を意識する

同じリクエストを何回送っても結果が変わらない性質を冪等といいます。GET・PUT・DELETE は冪等、POST は非冪等です。決済など「二重実行されると困る」POSTには、クライアントが生成した Idempotency-Key ヘッダーを受け取り、同じキーの再送は最初の結果を返す設計にします。

3. ステータスコードで結果を伝える

レスポンスの成否は HTTP ステータスコードで表現します。ボディだけで判断させる設計は避けましょう。

200 OK          # 成功
201 Created     # 作成成功
400 Bad Request # リクエストが不正
401 Unauthorized# 認証が必要
404 Not Found   # リソースが存在しない
500 Server Error# サーバー側の異常

4. エラーは構造化して返す

エラー時も一貫した JSON 形式で、原因が分かる情報を返します。

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "メールアドレスの形式が正しくありません",
    "field": "email"
  }
}

5. バージョニングで後方互換を守る

API は一度公開すると簡単には変えられません。URL にバージョンを含め、破壊的変更に備えます。

/v1/users
/v2/users

6. 一覧はページネーション・フィルタ・ソートを前提に

データ量が増えても破綻しないよう、一覧エンドポイントには最初から絞り込み用パラメータを用意します。専用の検索エンドポイントを作るより一貫します。

GET /users?status=active&role=admin      # フィルタ
GET /users?sort=-created_at              # ソート（-は降順）
GET /users?page=2&limit=20               # ページネーション
GET /users?q=tanaka                      # キーワード検索

レスポンスには合計件数や次ページの有無も含めます。

{
  "data": [ /* ... */ ],
  "meta": { "page": 2, "limit": 20, "total": 137 }
}

7. 認証は Authorization ヘッダーで

APIキーやトークンはURLやクエリに入れず、Authorization: Bearer <token> ヘッダーで渡します。ユーザー認可が必要なら OAuth 2.0 / OIDC、サーバー間ならAPIキーやクライアントクレデンシャルが一般的です。認証エラーは 401（未認証）、権限不足は 403（認証済みだが不許可）と使い分けます。

8. セキュリティと運用の基本

• 常時 HTTPS。平文HTTPは受け付けない。
• レートリミットを入れ、超過時は 429 Too Many Requests と Retry-After を返す。
• ブラウザから叩くなら CORS を許可オリジンを絞って設定。
• 入力は必ずサーバー側でバリデーションし、エラーは 422 または 400 で返す。
• レスポンスに不要な内部情報（スタックトレース、SQL）を含めない。

REST と GraphQL の使い分け

エンドポイントが素直に決まり、CDNやHTTPキャッシュを効かせたいなら REST。画面ごとに必要な項目が大きく異なり、過剰取得・N+1リクエストを減らしたいなら GraphQL が向きます。多くの業務APIはRESTで十分です。

よくある質問

URLの単語区切りはハイフンとアンダースコアどちら？

パスはケバブケース（ハイフン）。クエリやJSONのキーは snake_case か camelCase をAPI全体で統一します。

PUTとPATCHの使い分けは？

PUTは全体置き換え（冪等）、PATCHは部分更新です。

検索・フィルタはどう設計する？

一覧エンドポイントにGETのクエリパラメータを足します。例: GET /users?status=active&sort=-created_at&page=2。

まとめ

良い API 設計の核心は「一貫性」と「予測可能性」です。リソース指向の URL、正しいメソッドとステータスコード、統一されたレスポンスとエラー、ヘッダー経由の認証——この基本を守るだけで、使う人にも保守する人にも優しい API になります。