REST API設計で気を付けること10選

API設計は「動くこと」だけではレビューを通りにくい

まず、API設計はバックエンド開発で避けて通れないテーマです。ReactやVueなどのフロントエンドから、Spring BootやNode.jsなどのREST APIを呼び出す構成では、APIの設計品質が開発効率に直結します。

一方で、一度フロントエンドや外部システムに使われ始めた仕様は、簡単には変更できません。URL、レスポンス形式、エラー形式を途中で変えると、利用している画面や連携先に影響が出るからです。

そのため実務のコードレビューでは、「とりあえず動くか」だけではなく、使いやすいREST API設計になっているか、将来変更しやすい構成になっているかが見られます。

そこでこの記事では、API設計でレビュー指摘されやすいREST APIのNG例を10個紹介します。URL設計、HTTPメソッド、ステータスコード、エラーレスポンス、ページング、Swagger(OpenAPI)によるドキュメント管理まで、実務で保守しやすいAPIを作るためのポイントを整理します。

API設計でレビュー指摘されること10選

まず、この記事で紹介するAPI設計の注意点を一覧で整理します。細かい実装以前に、この10項目を押さえておくだけでも、レビュー指摘される確率はかなり下げられます。

番号	レビュー指摘されやすいこと	起こる問題
1	URLに動詞を書いてしまう	RESTらしくなく、APIの意味がぶれる
2	HTTPメソッドを正しく使っていない	取得・作成・更新・削除の意図が分かりにくい
3	ステータスコードを全部200で返す	成功と失敗を判定しづらい
4	エラーレスポンスの形式がバラバラ	フロントエンドの共通処理が難しくなる
5	命名規則が統一されていない	実装者が毎回迷う
6	一覧取得でページングを考慮していない	データ増加時に重くなる
7	検索・絞り込み・並び替えのルールがバラバラ	API利用者が混乱する
8	Entityをそのまま返している	不要情報や機密情報を返す危険がある
9	APIのバージョニングを考えていない	破壊的変更に弱い
10	Swaggerなどでドキュメントを管理していない	仕様共有が属人化する

1. APIのURLに動詞を書いてしまう

まず、API設計で指摘されやすいのが、URLに処理内容を書いてしまうパターンです。URLは「何を扱うか」を表し、処理内容はHTTPメソッドで表現します。

悪い例

/getUsers
/createUser
/updateUser
/deleteUser

良い例

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

例えば、usersはリソースであり、取得・作成・更新・削除はメソッド側で判断します。そのため、URLにgetやcreateのような動詞を入れなくても、処理の意図を表現できます。

2. APIのHTTPメソッドを正しく使っていない

次に、API設計ではHTTPメソッドの意味を守ることが重要です。例えば、データ取得なのにPOSTを使うと、API利用者が意図を読み取りにくくなります。

悪い例: POST /getUser
良い例: GET /users/1

GETは取得、POSTは作成、PUTは全体更新、PATCHは部分更新、DELETEは削除に使います。なお、HTTPメソッドの基本はMDNのHTTP request methodsでも確認できます。

3. ステータスコードを全部200で返している

また、すべてのレスポンスを200 OKで返す設計も、レビュー指摘されやすいポイントです。成功と失敗をレスポンスボディだけで判定させると、フロントエンド側の共通処理が複雑になります。

悪い例

{
  "success": false,
  "message": "ユーザーが見つかりません"
}

良い例

HTTP/1.1 404 Not Found

{
  "code": "USER_NOT_FOUND",
  "message": "ユーザーが見つかりません"
}

つまり、HTTPステータスコードはAPIの処理結果を表す重要な情報です。成功なら200系、リクエスト不備なら400系、サーバー側の問題なら500系を返すと、エラー処理を整理しやすくなります。ステータスコードの意味はMDNのHTTP response status codesも参考になります。

4. エラーレスポンス形式が統一されていない

一方で、ステータスコードだけを正しくしても、エラーレスポンスの形式がバラバラだと扱いにくくなります。エンドポイントごとに形式が違うと、画面側の実装が複雑になるからです。

{
  "code": "VALIDATION_ERROR",
  "message": "入力内容に誤りがあります",
  "details": [
    {
      "field": "name",
      "message": "名前は必須です"
    }
  ]
}

特にバリデーションエラーは、field単位で返すとフォーム画面と相性が良いです。そのため、エラーコード、表示用メッセージ、詳細情報の形式をプロジェクト内で統一しておくと安全です。

5. 命名規則が統一されていない

なお、API設計では、URLだけでなくJSONのプロパティ名も重要です。camelCaseにするかsnake_caseにするかはプロジェクト次第ですが、混在させないことが重要です。

{
  "userId": 1,
  "userName": "田中",
  "createdAt": "2026-06-01T10:00:00+09:00"
}

例えば、TypeScriptやJavaScriptのフロントエンドではcamelCaseに寄せるケースが多いです。ただし、バックエンドやDBの都合だけで命名を混在させると、API利用者が毎回迷います。

6. APIの一覧取得でページングを考慮していない

次に、一覧取得APIで全件取得する設計は危険です。最初は100件でも、将来10万件になればレスポンスが重くなります。

GET /users?page=1&limit=20

{
  "items": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

そのため、一覧APIではページング、取得件数、総件数を設計しておくと安全です。データが少ない段階でも、将来増える前提でAPI設計をしておくことが重要です。

7. 検索・絞り込み・並び替えルールがバラバラ

さらに、検索条件の名前がエンドポイントごとに違うと、利用者が混乱します。keyword、sort、order、page、limitなど、プロジェクト内でクエリパラメータのルールを決めておくと一貫性が高まります。

GET /users?keyword=tanaka&status=active&sort=createdAt&order=desc&page=1&limit=20

ただし、検索条件を増やしすぎるとAPIの責務が曖昧になります。必要に応じて、検索専用エンドポイントや検索条件DTOを用意することも検討します。

8. Entityをそのままレスポンスで返している

一方で、バックエンド実装で特に注意したいのが、DBのEntityをそのままAPIレスポンスにしてしまうことです。Entityには、画面に返すべきでない情報が含まれることがあります。

public record UserResponse(
    Long id,
    String name
) {}

{
  "id": 1,
  "name": "田中"
}

例えば、パスワード、内部メモ、削除フラグ、管理用カラムなどは返すべきではありません。したがって、レスポンス用DTOへ変換する設計が安全です。

9. APIのバージョニングを考えていない

実際には、APIは一度公開すると簡単には変更できません。特に外部システムや別チームが利用している場合、レスポンス形式の変更は破壊的変更になります。

/api/v1/users
/api/v2/users

もちろん、最初から何でもv2に分ければ良いわけではありません。ただし、既存利用者を壊す可能性がある変更に備えて、バージョニングの方針はREST API設計の段階で考えておくべきです。

10. Swagger(OpenAPI)でドキュメントを管理していない

最後に、REST API設計ではドキュメント管理も重要です。なぜなら、実装者だけが分かるAPIは、チーム開発では使いづらいAPIになるからです。

Swagger(OpenAPI)を使うと、URL、HTTPメソッド、パラメータ、レスポンス、ステータスコードをブラウザ上で確認できます。なお、OpenAPIの仕様はOpenAPI Specificationとして公開されています。

Swaggerで確認できること	内容
URL	/users/{id} などのエンドポイント
HTTPメソッド	GET / POST / PUT / PATCH / DELETE
パラメータ	PathVariable、Query Parameter、Request Body
レスポンス	正常時・異常時のJSON形式
ステータスコード	200、201、400、404、500など

API設計で迷ったときのチェックリスト

チェック項目	確認すること
URL	動詞ではなく名詞になっているか
HTTPメソッド	取得・作成・更新・削除の意味に合っているか
ステータスコード	成功・失敗をHTTPステータスで表現できているか
エラー形式	API全体で統一されているか
命名規則	camelCaseやsnake_caseが混在していないか
ページング	一覧取得で大量データに耐えられるか
DTO	Entityをそのまま返していないか
Swagger	API仕様をチームで確認できるか

API設計を学ぶと実務で何が変わるのか

その結果、API設計を学ぶメリットは、単にきれいなAPIを作れることだけではありません。フロントエンドとの連携、コードレビュー、仕様変更、障害調査など、実務のさまざまな場面で効果があります。

効果	実務で変わること
レビューに強くなる	なぜこのURLなのか、なぜこのステータスコードなのかを説明できる
連携が楽になる	フロントエンドがAPI仕様を理解しやすくなる
保守しやすくなる	後から仕様変更が入っても影響範囲を抑えやすい

API設計でよくある質問

API設計ではURLに動詞を書いてはいけませんか？

基本的には、URLは名詞でリソースを表し、操作はHTTPメソッドで表現します。ただし、ログインや検索など、単純なCRUDに収まりにくい処理では、プロジェクト内でルールを決めて一貫させることが重要です。

PUTとPATCHはどう使い分けますか？

一般的には、PUTはリソース全体の置き換え、PATCHは一部項目の更新に使います。なお、実務ではAPI利用者が誤解しないように、リクエストボディの形式と更新範囲をドキュメントに明記します。

API仕様でSwaggerとOpenAPIは何が違いますか？

OpenAPIはAPI仕様を記述する標準的な仕様です。一方で、SwaggerはOpenAPI仕様を扱うツール群の名前として使われることが多いです。現場では「SwaggerでAPI仕様を見る」と表現されることもあります。

まとめ：API設計は「使う人が迷わないこと」が重要

最後に整理すると、API設計で重要なのは、単にControllerを作ってJSONを返すことではありません。使う人が迷わず、変更しやすく、エラー時にも原因を判断しやすいAPIを作ることです。

また、今回紹介した10個のポイントを押さえるだけでも、API設計の品質は大きく変わります。特に、URL設計、HTTPメソッド、ステータスコード、エラーレスポンス、DTO、Swagger(OpenAPI)は、実務でもレビュー指摘されやすい項目です。

避けたい設計	意識したい設計
URLに動詞を書く	URLはリソース名で設計する
全部200で返す	適切なHTTPステータスコードを返す
エラー形式がバラバラ	共通のエラーレスポンス形式にする
Entityをそのまま返す	DTOに変換して必要な情報だけ返す
仕様書がない	Swagger(OpenAPI)でAPI仕様を共有する

つまり、バックエンドエンジニアとして設計力を上げたい場合は、まずAPI設計の基本を押さえることが重要です。API設計の品質は、チーム開発のしやすさやシステムの保守性に直結します。

API設計やバックエンド開発の実務スキルを伸ばしたい方は、まず「使う側が迷わない仕様になっているか」を意識してみてください。