REST APIのベストプラクティスを鵜呑みにしない方がいい理由

この記事の最終更新日: 2026年6月1日

REST APIを学んでいると、よく次のような「ベストプラクティス」を見かけます。

• URLには名詞を使う
• GETは取得、POSTは作成に使う
• PUTは全体更新、PATCHは部分更新に使う
• ステータスコードを正しく使う
• レスポンス形式を統一する
• APIにはバージョンを付ける
• エンドポイントはなるべくRESTfulに設計する

どれも基本的には大切です。

実際、API設計に慣れていない段階では、こうしたベストプラクティスを学ぶことで、かなり設計しやすくなります。

しかし、注意したいのは、ベストプラクティスは絶対ルールではない ということです。

REST APIのベストプラクティスを何も考えずに鵜呑みにすると、かえって使いにくいAPIになったり、実務に合わない設計になったりすることがあります。

この記事では、REST APIのベストプラクティスを鵜呑みにしない方がいい理由を、具体例を使って解説します。

ベストプラクティスとは何か？

ベストプラクティスとは、多くの現場や経験から「こうすると良いことが多い」とされている設計や実装の考え方です。

REST APIであれば、たとえば次のようなものがあります。

これらはどれも有用です。

ただし、ベストプラクティスはあくまで 判断材料 です。

どのプロジェクトでも、どの画面でも、どのチームでも、常にそのまま適用すればよいわけではありません。

鵜呑みにしない方がいい理由

REST APIのベストプラクティスを鵜呑みにしない方がいい理由は、主に次の通りです。

• プロジェクトの目的によって最適解が変わる
• 業務仕様によってRESTだけでは表現しにくい操作がある
• チームのスキルや運用体制によって現実的な設計が変わる
• 既存システムとの互換性を考える必要がある
• 完璧なRESTを目指すと、かえって複雑になることがある

API設計で大切なのは、ルールを守ること自体ではありません。

大切なのは、使う人にとってわかりやすく、安全で、変更に強いAPIにすること です。

理由1：プロジェクトによって最適な設計は変わる

REST APIの設計は、プロジェクトの性質によって最適解が変わります。

たとえば、次のようなプロジェクトを考えてみます。

たとえば、外部公開APIであれば、ステータスコード、エラー形式、バージョニング、互換性をかなり厳密に考える必要があります。

一方、社内だけで使う小さな管理画面APIであれば、過度に設計を複雑にするより、開発スピードや保守しやすさを優先した方がよい場合もあります。

つまり、「正しいREST API設計」は一つではありません。

プロジェクトの目的に合わせて、どこまで厳密に設計するかを判断する必要があります。

理由2：RESTだけでは業務アクションを表現しにくいことがある

REST APIでは、基本的にリソースに対する操作をHTTPメソッドで表現します。

たとえば、ユーザー情報であれば次のように設計できます。

GET    /users
GET    /users/1
POST   /users
PUT    /users/1
PATCH  /users/1
DELETE /users/1

これは非常にわかりやすい設計です。

しかし、実務では単純なCRUDだけでは表現しにくい操作があります。

たとえば、次のような業務アクションです。

• 注文をキャンセルする
• 請求書を送信する
• 記事を公開する
• パスワード再設定メールを送る
• CSVをエクスポートする
• 審査を承認する
• 予約を確定する

これらをすべてCRUDに当てはめようとすると、逆にわかりにくくなることがあります。

たとえば、注文キャンセルをRESTっぽく表現しようとして、次のようにすることもできます。

PATCH /orders/1

{
  "status": "cancelled"
}

単にステータスを変更するだけなら、これで十分です。

しかし、実際のキャンセル処理で次のような副作用がある場合はどうでしょうか。

• 在庫を戻す
• 決済を取り消す
• ユーザーにメールを送る
• 管理者に通知する
• キャンセル履歴を残す

この場合、単なるステータス更新というより、「注文キャンセル」という業務処理です。

そのため、次のようなAPIの方が意図が伝わりやすい場合があります。

POST /orders/1/cancel

これは純粋なREST設計から見ると少しアクション寄りです。

しかし、業務上の意味は明確です。

ベストプラクティスにこだわりすぎて、かえってAPIの意味が伝わりにくくなるなら本末転倒です。

理由3：「URLには動詞を使わない」を厳密に守りすぎると不自然になる

REST APIでは、よく「URLには動詞ではなく名詞を使う」と言われます。

悪い例として、次のようなAPIが挙げられます。

GET /getUsers
POST /createUser
POST /deleteUser

改善例は次のようになります。

GET    /users
POST   /users
DELETE /users/1

これは基本としては正しいです。

しかし、業務アクションまで無理に名詞だけで表現しようとすると、不自然になることがあります。

たとえば、請求書を送信するAPIを考えます。

POST /invoices/1/send

これは動詞を含んでいますが、意味はかなり明確です。

これを無理に名詞だけにしようとして、次のようにするとどうでしょうか。

POST /invoice-send-requests

または、

POST /invoices/1/sending

設計として成立しないわけではありません。

しかし、チームや利用者にとって POST /invoices/1/send の方がわかりやすい場合もあります。

つまり、「URLには絶対に動詞を使わない」と考えるのではなく、まずは次のように考える方が実務的です。

基本はリソースを名詞で表す。
ただし、業務アクションとして明確な場合は、動詞的な表現も検討する。

ベストプラクティスは、設計をわかりやすくするための手段です。

ルールを守ることで逆にわかりにくくなるなら、見直した方がよいです。

理由4：HTTPメソッドの使い分けも現場事情に左右される

REST APIでは、HTTPメソッドを次のように使い分けます。

これは基本です。

しかし、実務では必ずしもきれいに分けられないことがあります。

たとえば、検索APIです。

基本的には、検索はGETで表現できます。

GET /users?keyword=山田&status=active

しかし、検索条件が複雑な場合、GETのクエリパラメータでは扱いづらいことがあります。

{
  "keyword": "山田",
  "statuses": ["active", "pending"],
  "created_at": {
    "from": "2026-01-01",
    "to": "2026-12-31"
  },
  "sort": [
    {
      "field": "created_at",
      "order": "desc"
    }
  ],
  "filters": [
    {
      "field": "department_id",
      "operator": "in",
      "value": [1, 2, 3]
    }
  ]
}

このような場合は、次のようにPOSTで検索条件を送る設計もあります。

POST /users/search

もちろん、検索なのにPOSTを使うことには注意点もあります。

GETのようにURLで共有しにくくなったり、キャッシュを活用しにくくなったりします。

しかし、複雑な検索条件を扱う業務システムでは、POST検索が現実的な選択になることもあります。

大切なのは、「検索は絶対GET」と決めつけることではありません。

GETのメリットとPOSTのメリットを比較して、そのAPIに合った方法を選ぶことです。

理由5：ステータスコードを細かく使い分けすぎると混乱することもある

HTTPステータスコードを正しく使うことは重要です。

たとえば、よく使うステータスコードには次のようなものがあります。

ただし、実務ではステータスコードを細かく使い分けすぎると、チーム内で判断がブレることがあります。

たとえば、入力エラーに対して次のどちらを返すべきか迷うことがあります。

400 Bad Request

422 Unprocessable Entity

どちらを使うかは、チームやフレームワークの方針によって変わります。

Laravelではバリデーションエラーに422を返すことが多いです。

一方で、API設計によっては入力不正を400に統一する場合もあります。

ここで重要なのは、「どちらが絶対に正しいか」よりも、プロジェクト内で一貫しているか です。

同じ種類のエラーなのに、あるAPIでは400、別のAPIでは422を返す方が問題です。

ベストプラクティスを調べて悩み続けるより、チームでルールを決めて統一する方が実務では重要です。

理由6：レスポンス形式の正解も一つではない

APIレスポンスの形式にも、いろいろな考え方があります。

たとえば、ユーザー詳細APIのレスポンスとして、次のような形があります。

{
  "id": 1,
  "name": "山田太郎",
  "email": "yamada@example.com"
}

一方で、常に data で包む設計もあります。

{
  "data": {
    "id": 1,
    "name": "山田太郎",
    "email": "yamada@example.com"
  }
}

さらに、メタ情報を含める設計もあります。

{
  "data": {
    "id": 1,
    "name": "山田太郎",
    "email": "yamada@example.com"
  },
  "meta": {
    "request_id": "abc123"
  }
}

一覧APIでは、ページネーション情報を含めるために次のような形式にすることもあります。

{
  "data": [
    {
      "id": 1,
      "name": "山田太郎"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 100
  }
}

どの形式が正解かは、APIの用途によります。

小さな内部APIであれば、シンプルなJSONを返す方が扱いやすいかもしれません。

外部公開APIであれば、data や meta を含めて拡張しやすい形式にする方がよいかもしれません。

つまり、レスポンス形式も「これが絶対正解」とは言えません。

重要なのは、次の点です。

• クライアント側が扱いやすいか
• 一覧と詳細で形式が大きくブレていないか
• エラー形式が統一されているか
• 将来的にメタ情報を追加しやすいか
• 不要に複雑になっていないか

ベストプラクティスよりも、実際にそのAPIを使う側の実装体験を考えることが大切です。

理由7：APIバージョニングも常に必要とは限らない

API設計では、よくバージョニングが推奨されます。

たとえば、次のような形式です。

/api/v1/users

将来的に大きな仕様変更が発生した場合は、次のように新しいバージョンを作ります。

/api/v2/users

外部公開APIやスマホアプリ向けAPIでは、バージョニングは非常に重要です。

なぜなら、古いクライアントがすぐに更新されるとは限らないからです。

しかし、すべてのAPIで最初から厳密なバージョニングが必要とは限りません。

たとえば、次のようなケースです。

• 社内管理画面だけで使うAPI
• フロントエンドとバックエンドを同じチームが同時に更新できる
• まだMVP段階で仕様変更が頻繁に起きる
• 外部利用者がいない

このような場合、最初から /api/v1 を付けるのは問題ありませんが、バージョニング運用を重くしすぎる必要はありません。

大切なのは、「誰がそのAPIを使っているのか」「破壊的変更がどれくらい問題になるのか」を考えることです。

理由8：HATEOASまで最初から追う必要はない

RESTの話を深掘りすると、HATEOASという考え方が出てきます。

HATEOASは、レスポンスの中に次に実行できる操作へのリンクを含める考え方です。

たとえば、次のようなレスポンスです。

{
  "id": 1,
  "status": "pending",
  "links": {
    "self": "/orders/1",
    "cancel": "/orders/1/cancel",
    "payment": "/orders/1/payment"
  }
}

これはRESTの考え方としては重要です。

しかし、一般的なWebアプリ開発で、初心者が最初からここまで厳密に実装する必要はほとんどありません。

多くの現場では、次のような基本を押さえるだけでも十分に実用的です。

• リソースを意識する
• HTTPメソッドを使い分ける
• ステータスコードを適切に使う
• JSON形式を統一する
• エラー形式を整える
• 認証・認可を正しく実装する

完璧なRESTを目指しすぎると、学習コストや実装コストが上がりすぎます。

初心者のうちは、まず実務でよく使う範囲から理解する方が効率的です。

理由9：既存システムとの互換性を無視できない

理想的なREST API設計があったとしても、実務では既存システムとの互換性を考えなければいけません。

たとえば、すでに次のようなAPIが使われているとします。

POST /getUserList
POST /updateUser

本来であれば、次のように直したいかもしれません。

GET   /users
PATCH /users/1

しかし、すでにフロントエンドやスマホアプリ、外部システムが古いAPIを使っている場合、いきなり変更すると動かなくなります。

この場合、理想的な設計に一気に変えるのではなく、段階的に移行する必要があります。

たとえば、次のような進め方です。

1. 新しいRESTfulなAPIを追加する
2. 既存APIはしばらく残す
3. フロントエンド側を新APIに移行する
4. 外部利用者に移行期間を案内する
5. 古いAPIを非推奨にする
6. 一定期間後に廃止する

API設計では、理想だけでなく、互換性と移行コストも重要です。

ベストプラクティスを知っていても、現場では「今すぐ直すべきか」「段階的に直すべきか」を判断する必要があります。

理由10：チームが理解できない設計は運用できない

どれだけ美しいAPI設計でも、チームが理解できなければ運用できません。

たとえば、次のような状態です。

• 一部の人しか設計意図を理解していない
• フロントエンド側が使い方に迷う
• エラー形式のルールが共有されていない
• PUTとPATCHの違いがチーム内で曖昧
• レビュー時に毎回同じ議論になる

この状態で高度なベストプラクティスを導入しても、実装がバラバラになります。

API設計では、理想的なルールよりも、チーム全体で守れるルールの方が重要です。

たとえば、まずは次のようなシンプルなルールから始めるだけでも効果があります。

取得はGET
作成はPOST
全体更新はPUT
部分更新はPATCH
削除はDELETE
URLは基本的に名詞にする
エラー形式は統一する
バリデーションエラーは422にする
認証エラーは401にする
権限エラーは403にする

最初から完璧な設計ガイドラインを作る必要はありません。

チームが理解できて、レビューで使えて、実装に反映できるルールにすることが大切です。

ベストプラクティスをどう使えばいいのか

では、REST APIのベストプラクティスは不要なのでしょうか。

もちろん、そうではありません。

ベストプラクティスは非常に有用です。

ただし、使い方が大切です。

ベストプラクティスは、次のように使うのがよいです。

そのまま暗記する
↓
なぜそうするのか理解する
↓
自分のプロジェクトに合うか考える
↓
チームでルール化する
↓
必要に応じて例外を許容する

大切なのは、「なぜそのベストプラクティスが存在するのか」を理解することです。

たとえば、「GETは取得に使う」というルールには、次のような理由があります。

• データを変更しないことが期待される
• キャッシュしやすい
• URLで共有しやすい
• ブラウザやツールと相性がよい
• ログから意図が読み取りやすい

この理由を理解していれば、複雑な検索でPOSTを使う場合にも、メリットとデメリットを比較して判断できます。

逆に、理由を理解せずに「検索はGETじゃないとダメ」と覚えていると、実務で柔軟な判断ができません。

鵜呑みにしてはいけないベストプラクティスの例

ここからは、鵜呑みにしやすいベストプラクティスをいくつか具体的に見ていきます。

例1：URLには絶対に動詞を入れてはいけない

基本的には、URLは名詞にする方がよいです。

GET /users
POST /orders
DELETE /articles/1

しかし、業務アクションの場合は動詞を使った方が自然なこともあります。

POST /orders/1/cancel
POST /invoices/1/send
POST /articles/1/publish

無理に名詞だけにして意味が伝わりにくくなるなら、動詞を使う選択もあります。

例2：検索は必ずGETにする

検索は基本的にGETが自然です。

GET /users?keyword=山田

ただし、検索条件が複雑な場合はPOSTの方が扱いやすいこともあります。

POST /users/search

{
  "keyword": "山田",
  "status": ["active", "pending"],
  "date_range": {
    "from": "2026-01-01",
    "to": "2026-12-31"
  }
}

GETの利点を捨てることにはなりますが、複雑な検索条件を扱う実務では妥当な判断になる場合があります。

例3：ステータスコードは細かく正確に使い分けるべき

ステータスコードを適切に使うことは大切です。

しかし、細かく使い分けすぎると、チーム内で判断が揺れることもあります。

たとえば、400と422、401と403、404と403などは迷いやすいポイントです。

この場合、重要なのは完璧な理論よりも、チーム内での統一です。

未ログインは401
ログイン済みだが権限なしは403
存在しないリソースは404
バリデーションエラーは422
予期しないサーバーエラーは500

このようにルール化しておくと、実装やレビューが安定します。

例4：レスポンスは必ずdataで包む

APIレスポンスを data で包む設計はよくあります。

{
  "data": {
    "id": 1,
    "name": "山田太郎"
  }
}

この形式は、meta や links を追加しやすいというメリットがあります。

一方で、小さな内部APIでは次のようなシンプルな形式の方が扱いやすい場合もあります。

{
  "id": 1,
  "name": "山田太郎"
}

どちらが正解かではなく、API全体で統一されているか、クライアント側が扱いやすいかを考えるべきです。

例5：PUTとPATCHを厳密に分けるべき

PUTは全体更新、PATCHは部分更新です。

基本的には、この理解で問題ありません。

PUT /users/1

{
  "name": "山田太郎",
  "email": "yamada@example.com",
  "age": 30
}

PATCH /users/1

{
  "age": 31
}

ただし、既存APIやフレームワークの都合で、PUTが部分更新のように実装されている現場もあります。

理想としては整理した方がよいですが、既存クライアントが使っている場合、すぐに変更できないこともあります。

その場合は、仕様書に明記したうえで、段階的に改善するのが現実的です。

初心者が持つべき考え方

初心者のうちは、まずベストプラクティスを素直に学ぶことが大切です。

最初から「現場による」と考えすぎると、基準がなくなってしまいます。

おすすめの学び方は次の順番です。

1. まず基本形を覚える
2. なぜその形が推奨されるのか理解する
3. 例外があることを知る
4. 実務では目的に合わせて判断する

たとえば、HTTPメソッドならまず次の基本を覚えます。

そのうえで、次のような例外を理解します。

• 複雑な検索ではPOSTを使うこともある
• 業務アクションでは /cancel や /send を使うこともある
• 既存APIとの互換性を優先することもある
• 社内APIでは過度な厳密さより実装速度を優先することもある

基本を知らずに例外を使うのは危険です。

一方で、基本だけを絶対視して例外を認めないのも実務では危険です。

API設計で本当に大切なこと

REST API設計で本当に大切なのは、ベストプラクティスを完全に守ることではありません。

本当に大切なのは、次のような観点です。

1. 意図が伝わること

APIを見たときに、何をするAPIなのかがわかることが重要です。

DELETE /users/1

これは、ユーザーを削除するAPIだとすぐにわかります。

一方で、次のようなAPIは意図が読み取りづらいです。

POST /execute

APIは、実装者だけでなく、利用者が理解できる形にするべきです。

2. 一貫性があること

API設計では、一貫性が非常に重要です。

たとえば、ユーザー削除ではDELETEを使っているのに、記事削除ではPOSTを使っていると混乱します。

DELETE /users/1
POST /deleteArticle

このようなブレを減らすために、チーム内で設計ルールを決めておく必要があります。

3. クライアントが扱いやすいこと

APIは、サーバー側の都合だけで設計してはいけません。

フロントエンドやスマホアプリなど、APIを利用する側が扱いやすいことも重要です。

たとえば、エラー形式が統一されていると、フロントエンドでエラー表示を実装しやすくなります。

{
  "message": "入力内容に誤りがあります",
  "errors": {
    "email": ["メールアドレスの形式が正しくありません"]
  }
}

逆に、APIごとにエラー形式が違うと、クライアント側の実装が複雑になります。

4. 安全であること

API設計では、安全性も重要です。

たとえば、GETで削除処理を行うのは避けるべきです。

GET /users/1/delete

GETは取得のためのメソッドであり、データ変更を伴う処理には向いていません。

削除であればDELETEを使うのが自然です。

DELETE /users/1

また、認証や認可も重要です。

ログインしていないユーザーに個人情報を返したり、権限のないユーザーが削除できたりすると、重大な問題になります。

5. 変更に強いこと

APIは一度使われ始めると、簡単には変更できません。

そのため、将来的な変更にある程度耐えられる設計が重要です。

たとえば、レスポンスに将来的にメタ情報を追加したいなら、最初から data で包む設計にしておくのも一つの選択です。

{
  "data": {
    "id": 1,
    "name": "山田太郎"
  }
}

外部クライアントが利用するAPIであれば、バージョニングも検討する必要があります。

/api/v1/users

ただし、変更に強くするために設計を複雑にしすぎると、開発速度が落ちます。

ここでもバランスが重要です。

ベストプラクティスを採用するか判断するチェックリスト

REST APIのベストプラクティスを採用するか迷ったら、次の観点で考えると判断しやすいです。

この設計はAPI利用者にとってわかりやすいか？
チーム内で一貫して使えるか？
将来の変更に耐えられるか？
セキュリティ上の問題はないか？
フロントエンド側の実装が複雑にならないか？
ログや監視で追いやすいか？
既存APIとの互換性を壊さないか？
今のプロジェクト規模に対して過剰設計ではないか？

ベストプラクティスを使うときは、「一般的に良いから」ではなく、「このプロジェクトでも良い理由があるか」を考えることが大切です。

悪いのはベストプラクティスではなく、思考停止である

ここまで、REST APIのベストプラクティスを鵜呑みにしない方がいい理由を説明してきました。

ただし、誤解してはいけないのは、ベストプラクティス自体が悪いわけではないということです。

むしろ、ベストプラクティスは非常に役立ちます。

問題なのは、理由を理解せずに機械的に適用することです。

たとえば、次のような考え方は危険です。

RESTではURLに動詞を入れてはいけないから、業務アクションでも絶対に動詞を使わない
検索はGETが正しいから、どれだけ条件が複雑でもGETにする
ステータスコードは細かく使うべきだから、チームで扱いきれないほど分類する
外部公開APIで使われる設計だから、社内の小さなAPIにもそのまま適用する

ベストプラクティスは、現場でより良い判断をするための道具です。

道具を使う目的を忘れてしまうと、かえって扱いづらい設計になります。

まとめ

REST APIのベストプラクティスは、API設計を学ぶうえで非常に役立ちます。

しかし、ベストプラクティスは絶対的な正解ではありません。

プロジェクトの目的、業務仕様、チームのスキル、既存システムとの互換性によって、最適な設計は変わります。

特に、次のような点には注意が必要です。

API設計で大切なのは、ベストプラクティスを暗記することではありません。

なぜそのルールがあるのかを理解し、自分のプロジェクトに合う形で使うことです。

REST APIは、サーバー側だけのものではなく、フロントエンド、スマホアプリ、外部サービスなど、さまざまな利用者との「契約」です。

だからこそ、ルールを守ることだけにこだわるのではなく、利用者にとってわかりやすく、変更に強く、安全に使えるAPIを目指すことが重要です。

daigoro

大阪のエンジニアが書いているブログ。