REST API設計であとから効いてくる判断ポイント
はじめに
Web アプリケーションのバックエンド開発を中心に仕事をしています。
Java / Spring Boot、Python / FastAPI などを使って REST API の設計・実装をしてきました。
これまでの開発では、中規模 SaaS のバックエンド設計を一人で担当し、API62 本を設計・実装した経験があります。
この記事では、
REST API を設計するときに「なぜその形にしたのか」を説明できるようになるための判断ポイント
をまとめます。
「正解集」ではなく、
あとから変更・拡張するときに効いてくる考え方を中心に書いていきます。
REST API 設計で“なんとなく”になりがちなポイント
REST API は、動くものを作るだけであれば比較的簡単です。
その一方で、次のような状態になりがちです。
- URL や HTTP メソッドを雰囲気で決めている
- とりあえず 200 でレスポンスを返している
- エラー設計は後回しになっている
- フロントからの要求にその場しのぎで対応している
最初は問題なく動いていても、
API の数が増えたり、仕様変更が入ったタイミングで一気に辛くなることが多いです。
設計で最初に決めている 3 つのこと
REST API を設計するとき、私はまず次の 3 点を意識しています。
1. リソースの単位は何か
この API で扱っている「主語」は何かを最初に決めます。
- user
- order
- product
など、名詞で表現できる単位を明確にします。
2. 責務の境界はどこか
この API がやること／やらないことを決めます。
- データ取得だけか
- 状態変更まで行うのか
- 他のリソースに影響を与えるのか
責務が曖昧だと、API が肥大化しやすくなります。
3. 変更されやすいポイントはどこか
- 今後、仕様変更が入りそうな部分
- 拡張されそうな項目
ここを意識しておくと、
URL 設計やレスポンス設計の判断がしやすくなります。
URL 設計で意識していること
名詞ベースで考える
URL は基本的に 名詞（リソース） で設計します。
/users
/users/{id}
/orders
動詞を URL に含めると、
HTTP メソッドとの責務が曖昧になりやすいためです。
階層を深くしすぎない
/users/{userId}/orders/{orderId}/items
このような階層は、
「本当にここまで必要か？」を一度立ち止まって考えます。
フロントエンド（React / Next.js）から使う視点で見ると、
必要以上に複雑な URL は扱いづらいことが多いです。
HTTP ステータスとエラー設計
200 ですべてを返さない
- 正常：200
- 入力不正：400
- 認証エラー：401
- 権限不足：403
- リソースなし：404
最低限、このあたりは明確に分けています。
エラーレスポンスを統一する
エラー時のレスポンス形式を揃えておくと、
- フロント側の実装が楽になる
- ログ・監視がしやすくなる
といったメリットがあります。
あとから効いてくる「非機能視点」
API 設計では、機能だけでなく非機能も重要です。
- ログに何を出すか
- 将来のバージョニングをどうするか
- 監視で何を検知したいか
このあたりを少しでも意識しておくと、
運用フェーズに入ったときの負担が大きく変わります。
実際に後悔した設計と学び
SaaS のバックエンドを一人で設計した際、
最初は「とりあえず動く API」を優先していました。
結果として、
- 責務が曖昧な API
- フロント都合に引きずられた URL 設計
になってしまい、後から整理するのに時間がかかりました。
今振り返ると、
最初に判断軸を決めておくことの重要性を強く感じています。
おわりに
REST API 設計に絶対的な正解はありません。
ただし、「なぜその設計にしたのか」を説明できるかどうかは大きな差になります。
Discussion