API設計でよくあるアンチパターン

はじめに

バックエンド開発をしていると、「使いづらいAPI」に出会うことがあります。

例えば
・レスポンス構造がバラバラ
・エンドポイントの命名が不統一
・仕様が曖昧
こういったAPIは「フロントの実装コストが上がる」「バグが増える」「保守が難しくなる」といった問題につながります。
この記事では、実務でよく見るAPI設計のアンチパターンについてまとめます。

① エンドポイントの命名が不統一

例えば下記のように動詞が混ざったり、命名ルールがバラバラだと、使う側が混乱します。

GET /getUsers
GET /user/list
POST /createUser

理想は👇

GET /users
POST /users
GET /users/{id}

👉 リソースベースで統一することが重要です

② レスポンス構造がバラバラ

// パターン①
{ "data": [...] }

// パターン②
{ "users": [...] }

// パターン③
[ ... ]

APIごとに形式が違うとパース処理が増え、バグの原因になるため、統一が必要です。

例👇

{
  "data": [...],
  "meta": { "total": 100 }
}

👉 レスポンスは統一ルールを持つ

③ ステータスコードの使い方が雑

よくあるのがこれ👇

200 OK（エラーなのに）

これだとエラーハンドリングが複雑になる、フロント側の実装が崩れる。

正しくは👇
・200 → 正常
・400 → クライアントエラー
・500 → サーバーエラー
👉 HTTPの意味を守ることが重要

④ フィールドの意味が曖昧

{
  "status": 1
}

これだけだと何のステータスか分からない。

改善👇

{
  "status": "active"
}

または

{
  "isActive": true
}

👉 名前と値で意味が分かる設計にする

まとめ

API設計でよくあるアンチパターンは下記です。
・命名が不統一
・レスポンス構造がバラバラ
・ステータスコードが適当
・フィールドの意味が曖昧

これらは「使う側の視点」を持つことでかなり改善できます。
APIは「内部実装」ではなく“他人が使うインターフェース”であることを意識することが重要です。

告知

もし興味があればですが、
案件に関わる中で一緒に開発できるエンジニアの方ともつながれたら嬉しいです。
・フリーランス
・副業
・業務委託
などで案件を探している方がいれば気軽にDMください。