はじめに
APIを設計するとき、「処理を1つにまとめるか」「複数のAPIに切り出すか」はよく悩むポイントかなと思います。
例えば、チーム作成と1人目のユーザー作成を同時にやるみたいな処理は、APIは2つがいいか、1つのAPIでやるかなど。
「APIの責務をどう分けるか」という設計かと思いますので、判断基準的なものを本記事にて、まとめていきます。
判断の指針
- 外部公開かどうか
- トランザクションの境界
- 再利用性
- 認可やポリシーの違い
外部公開かどうか
外部に出すAPIは粒度を小さく、リソース指向で分割した方がいい。
外部に提供するなら、責務が明確で再利用しやすい形にしておく方が扱いやすい。
逆に自社プロダクト専用で、UIの特定フローにしか使わないなら、1つにまとめても問題は少ない。
再利用性
上記と少し重なるが、、、
処理の一部が他のシナリオでもよく使われるなら、APIを1本にまとめるのは避けた方がいい。
逆に一度しか使わない専用フローなら、まとめても困らない。
トランザクションの境界
複数の処理を必ず同時に成功させたいかどうかが判断材料。
同じDB内なら1つのAPIにまとめてトランザクションで扱うのが自然。
違うDBの場合は、慎重にではあるが、1つのトランザクションにして、要件に合わせてデアはあるが、どっちかが失敗したらどっちも失敗でロールバックする仕組みが安全そう。
認可やポリシーの違い
未認証で実行できる処理と、認証や検証が必要な処理を同じAPIに押し込むと不自然になる。認可境界やポリシーが違う場合は素直に分けた方が整理しやすい。
設計スタイルについて
そもそもの設計スタイルとして、考えたのが、、、
「リソース指向で粒度を小さく切るべきか」
「ユースケースごとにまとめるべきか」
という二択の議論。
ただ結局は、実務でよく使われているのはハイブリッド。
どちらか一方ではなく、両方を組み合わせるのがバランスが良さそう！
まとめ
APIをまとめるか分けるかは「正解が一つ」ではなく、状況に応じて選ぶものだと学びました。
今回整理してみて、API設計は技術的な粒度の話だけじゃなく「誰が使うか」「どう運用するか」を含めて考えるべきものだと改めて理解できました。