REST API Best Practices: A Practical Checklist for 2026 — txt1.ai

3年前、私はあるスタートアップが資金230万ドルを燃やすのを見ました。その理由は、彼らのAPI設計が根本的に間違っていたため、各新機能のためにコードベースの半分を書き直さなければならなかったからです。私はサラ・チェンで、過去12年間、3つの異なるユニコーンサートアップで主要APIアーキテクトとして働いてきました。月に470億リクエスト以上を処理するシステムを設計しています。私が学んだことは、REST API設計は硬直したルールに従うことではなく、技術的な優秀さか技術的債務に積み重なる意図的な選択をすることなのです。

RESTが事実上の標準になってから、状況は大きく変わりました。2026年、私たちはエッジコンピューティング、毎秒数千のAPIコールを行うAI駆動アプリケーション、そして世界のどこからでも100ms未満のレスポンスタイムを期待するユーザーに対処しています。古い「RESTの原則に従いなさい」というアドバイスはもはや通じません。現代の現実を考慮に入れた実用的で戦闘実績のあるチェックリストが必要です。

この記事がそのチェックリストです。私は、日々数百万の収益を処理する企業のためにAPIを設計する際に使用する正確なフレームワークを共有しています。これは理論的なベストプラクティスではなく、スケールするAPIとその重みで崩れてしまうAPIを分けるパターンです。

リソース名付け: 誰もが間違える基盤

最初に、無関係に思えるが、ほとんどの他の問題よりも多くの下流の問題を引き起こすものから始めましょう: リソース名付けです。私のキャリアで200以上のAPI設計をレビューしてきましたが、その60%が一貫性のない、または混乱を引き起こすリソース名付けで、級数的な問題を生んでいると推定しています。

以下がコアの原則です: あなたのURLはリソース階層を説明する文章のように読まれるべきです。コレクションには複数形名詞を使用し、ネストは浅く保ち（最大2-3レベル）、無情に一貫性を保ってください。私が現在の会社に入社したとき、彼らのAPIには/getUser、/user-list、/users/fetchといったエンドポイントがあり、すべて類似のことを行っていました。私たちはその混乱を解決するのに3ヶ月を費やしました。

私が推奨するパターン:

• コレクション: /api/v1/users、/api/v1/orders、/api/v1/products
• 特定のリソース: /api/v1/users/12345、/api/v1/orders/ord_abc123
• サブリソース: /api/v1/users/12345/orders、/api/v1/orders/ord_abc123/items
• リソースへのアクション: /api/v1/orders/ord_abc123/cancel（POST）、/api/v1/users/12345/verify-email（POST）

何が欠けているのか気付きましたか？URLパス内の動詞（非CRUDアクションを除く）。HTTPメソッドが動詞です。GET /usersは「ユーザーを取得する」という意味です。POST /usersは「ユーザーを作成する」という意味です。DELETE /users/123は「ユーザー123を削除する」という意味です。これは美的なものではなく、あなたのAPIを予測可能にし、開発者の認知負荷を軽減します。

非CRUD操作のためには、実用的なアプローチを採用します。はい、純粋主義者はすべてがCRUDにマッピングされるべきだと言いますが、実際の世界では「注文をキャンセルする」、「メールを確認する」や「送料を計算する」といった操作があります。私はこれらをアクションエンドポイントに対するPOSTリクエストとして表現します: POST /orders/123/cancel。鍵は一貫性です—あなたのパターンを文書化し、信心深くそれに従ってください。

もう1つの重要な詳細: 複数の単語のリソースにはケバブケースを使用します（/shipping-addresses、/shippingAddressesや/shipping_addressesではなく）。多くの文脈ではURLはケースに対して区別しないため、ケバブケースが最も普遍的に読みやすい形式です。この単純な規則で回避できたケースセンシティビティによる問題が原因のプロダクションインシデントを見てきました。

HTTPメソッドとステータスコード: 正しい言語を使う

リソース名付けがあなたのAPIの語彙であれば、HTTPメソッドとステータスコードはその文法です。そして、人間の言語と同様に、文法を間違えると理解するのが難しくなります—たとえ人々が最終的にあなたの意味を理解できたとしても。

私が繰り返し見る2つの一般的なアンチパターンがあります。まず、「動作する」という理由ですべてにPOSTを使用するAPIです。次に、エラーであっても各レスポンスに200 OKを返すAPIで、実際のステータスがレスポンス本文に埋没しています。これら2つのパターンは、キャッシュが難しく、デバッグが難しく、標準ツールとの統合が難しいAPIを生み出します。

以下は、実際の使用に基づいたメソッドごとの内訳です:

GET: リソースを取得します。アイデポテントで安全でなければなりません（副作用なし）。状態を変更する操作にGETを使用しないでください—「最終アクセスされたタイムスタンプを更新するだけ」と言われても構いません。これはミドルウェアの役割です。GETリクエストはキャッシュ可能であり、状態変更を混ぜることはキャッシングの仮定を壊します。私が関わったあるシステムでは、GETのアイデポテンシーを正しく実装し、HTTPキャッシングヘッダーを追加することでデータベースの負荷を73%減少させました。

POST: 新しいリソースを作成するか、アクションをトリガーします。POSTは非アイデポテント操作のための主力です。リソースを作成する際には、新しいリソースを指すLocationヘッダー付きで201 Createdを返します。アクションをトリガーする場合は、結果を説明するレスポンス本文と共に200 OKまたは202 Accepted（非同期処理のため）を返します。

PUT: リソース全体を置き換えます。これは多くの開発者が混乱するところです。PUTは提供された表現で完全なリソースを置き換える必要があります。PUTリクエストで一部のフィールドのみを送信した場合、そのフィールドだけがリソースに残るべきです（他のフィールドはデフォルトまたはnullに設定されるべきです）。実際には、私はPUTを控えめに使用します—通常はクライアントが完全な状態を真に管理するリソースでのみ使用します。

PATCH: リソースを部分的に更新します。これは、多くの開発者がPUTを望んでいる時に実際に求めるものです。PATCHを使用すると、変更したいフィールドのみを送信できます。私は通常、リクエスト形式にJSON Patch (RFC 6902)またはJSON Merge Patch (RFC 7396)を使用します。私が現在の会社で、94%の更新操作はPATCHを使用し、PUTではありません。

DELETE: リソースを削除します。成功時には204 No Contentを返します（レスポンス本文は必要ありません）、または削除に関する情報を返す場合は200 OKを返します。DELETEをアイデポテントにしてください—複数回呼び出しても一度呼び出したのと同じ効果を持つべきです。リソースがすでに削除されていても204を返します。

ステータスコードについては、99%のシナリオをカバーする実用的なサブセットを使用します:

• 200 OK: データを返す成功したGET、PUT、PATCH、またはPOST
• 201 Created: リソースを作成する成功したPOST
• 202 Accepted: 非同期処理のために受け入れられたリクエスト
• 204 No Content: レスポンス本文なしの成功したDELETEまたは更新
• 400 Bad Request: クライアントが無効なデータを送信（詳細なエラーメッセージ付き）
• 401 Unauthorized: 認証が必要または失敗
• 403 Forbidden: 認証はされたが、このリソースに対して権限がない
• 404 Not Found: リソースが存在しない
• 409 Conflict: 現在の状態とリクエストが矛盾する（例: 重複したメール）
• 422 Unprocessable Entity: バリデーションが失敗しました（バリデーションエラーには400よりもこれを好みます）
• 429 Too Many Requests: レート制限を超過
• 500 Internal Server Error: 当社の側で何かが壊れました
• 503 Service Unavailable: 一時的な障害またはメンテナンス

重要な洞察: ステータスコードはHTTPレベルの意味論のためのものであり、レスポンス本文はアプリケーションレベルの詳細のためのものです。400のレスポンスは常に「無効なデータを送信しました」を意味するべきですが、レスポンス本文はどのフィールドがどのように間違っていたかを正確に説明します。

バージョン管理: 痛みのない将来対応

私は3回の主要なAPIバージョン移行を経験し、それぞれが何を避けるべきかについて痛みを伴う教訓を教えてくれました。最悪なのは、18ヶ月かかり、47のクライアントアプリケーション全体での更新の調整が必要だったv1からv2への移行でした。そのプロセスの中で、2つの主要な顧客を失いました。彼らの統合チームが変更についていけなかったからです。