APIのURLに動詞を使うべきですか？

REST APIでは原則としてURLに動詞を使わず、名詞でリソースを表します。操作はHTTPメソッド（GET・POST・PUT・DELETE）で表現します。ただし、/search、/loginなどのアクション型エンドポイントでは動詞を使うこともあります。

APIのバージョニングはURLパスとヘッダーどちらが良いですか？

URLパス方式（/v1/、/v2/）はブラウザのアドレスバーや、ブックマーク・ログから直接確認できるため、開発者にとって直感的でデバッグしやすいです。ヘッダー方式はURLをクリーンに保てますが、テストや共有が手間になります。多くの場合URLパス方式が推奨されます。

APIドキュメントを自動生成するにはどうすればよいですか？

OpenAPI（Swagger）仕様でAPIを記述すると、Swagger UI・ReDocなどのツールでインタラクティブなドキュメントを自動生成できます。コードファーストアプローチではFastAPIやNestJSのようなフレームワークがコードからOpenAPIドキュメントを自動生成します。

API設計のベストプラクティス10選【REST API編・2026年版】

はじめに

良いAPI設計は、利用者の開発体験を大きく左右します。直感的で一貫性のあるAPIは学習コストが低く、間違いが起きにくく、長期的な保守性に優れています。本記事では、実際の現場で役立つREST API設計のベストプラクティスを10の観点からまとめました。

1. リソースには名詞を使う

URLはリソース（物・概念）を表すべきです。動作（動詞）はHTTPメソッドで表現します。

良い例：GET /users、POST /orders、DELETE /products/123
悪い例：GET /getUsers、POST /createOrder、DELETE /deleteProduct/123

リソース名は複数形を使うのが一般的です。/user より /users の方が「ユーザーのコレクション」を直感的に表せます。

2. HTTPメソッドを正しく使う

各HTTPメソッドのセマンティクス（意味）を守ることで、APIの動作を直感的に理解できるようになります。

GET：リソースの取得（副作用なし・冪等）
POST：リソースの作成
PUT：リソースの完全置換（冪等）
PATCH：リソースの部分更新
DELETE：リソースの削除（冪等）

なお、GETリクエストは副作用を持つべきではありません。データの取得にGETを使い、変更操作にはPOST・PUT・PATCH・DELETEを使います。

3. 一貫した命名規則を使う

URLはkebab-case（ハイフン区切り）が推奨されます（例：/user-profiles）。クエリパラメーターとJSONフィールドはsnake_case（アンダースコア区切り）またはcamelCaseを統一して使います。大切なのは「プロジェクト内で統一する」ことです。

4. 適切なHTTPステータスコードを返す

HTTPステータスコードはAPIのレスポンスの意味を伝える重要な情報です。「成功でも失敗でも常に200を返す」設計は避けてください。

200 OK：成功
201 Created：リソース作成成功（POSTの成功時）
204 No Content：成功だがボディなし（DELETE成功時など）
400 Bad Request：リクエストの形式・内容が不正
401 Unauthorized：認証が必要
403 Forbidden：認証済みだが権限なし
404 Not Found：リソースが存在しない
409 Conflict：競合（重複登録など）
422 Unprocessable Entity：バリデーションエラー
429 Too Many Requests：レート制限超過
500 Internal Server Error：サーバー内部エラー

5. 意味のあるエラーレスポンスを返す

エラー発生時は、エラーコードと人間が読めるメッセージを含む構造化されたJSONを返します。エラーコードがあると、クライアントがエラーの種類を機械的に判別して適切な処理を行えます。

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

6. ページネーションを実装する

大量データを返すエンドポイントにはページネーションを実装します。主な方式はオフセットページネーション（?page=2&limit=20）とカーソルページネーション（?cursor=xxx）です。カーソル方式はリアルタイムデータや大規模データに適しています。

7. フィルタリング・ソート・検索をクエリパラメーターで実装する

リソースのフィルタリングはクエリパラメーターで表現します。

フィルター：GET /products?category=electronics&status=active
ソート：GET /products?sort=price&order=asc
フィールド指定：GET /users?fields=id,name,email

8. バージョニングを設計に組み込む

APIは時間とともに進化します。最初からバージョニングを設計に組み込むことで、後方互換性を保ちながら機能追加・変更が行えます。URLパスにバージョンを含める方法が最も普及しています。

URLパス：/v1/users、/v2/users
ヘッダー：Accept: application/vnd.api.v2+json

既存バージョンのAPIは、事前に十分な告知期間（一般的に6〜12ヶ月）を設けてから廃止します。

9. CORS（クロスオリジンリソース共有）を適切に設定する

ブラウザから直接APIを呼び出す場合、CORSの設定が必要です。アクセスを許可するオリジン（ドメイン）を明示的に指定し、「Access-Control-Allow-Origin: *」のようなワイルドカード指定は認証が必要なAPIでは避けてください。

10. APIドキュメントを整備する

どんなに設計が優れていても、ドキュメントがなければ使えません。OpenAPI仕様（旧Swagger）を採用することで、インタラクティブなドキュメント（Swagger UI・ReDoc）の自動生成が可能です。ドキュメントには各エンドポイントの説明・リクエスト/レスポンスのスキーマ・認証方法・エラーコード一覧を必ず含めてください。

まとめ

良いAPI設計は一日にして成らず、利用者の視点に立った継続的な改善が重要です。本記事の10のベストプラクティスを出発点として、チーム内でAPI設計ガイドラインを策定し、コードレビューで一貫性を保つことをお勧めします。API図鑑でも様々なAPIの設計パターンを参考にしてみてください。