私はITエンジニアとしてバックエンドの対応を主としてるつもりですが（あくまで個人的な所感）、いまだにAPIの設計として何が適切かは手探りです。仕事やってて、けっこう互いのこだわりもあるし、中々意見が衝突するといったこともありました。たまにですが、どう設計すれば良いですかとか聞かれることもあるので、今回は個人的にAPI設計で気をつけてることを書いてみます。なお、この記事で取り上げるAPIの守備範囲として、画面から受け付けるいわゆるWebAPIに限らず、例えばバッチで呼び出したり外部公開するといった、特に用途を限定しないことを前提としています。
まず、個人的にAPIを考える上で意識している観点としては、3つあります。DBのスキーマ、画面、ドメインです。以下ではこの3つの観点について、もう少し深堀りしていきます。
【DBのスキーマ】
APIの設計で一番シンプルなのは、DBのスキーマに合わせることです。以下の記事にある、CRUDのような形式です。
これはこれで分かりやすさはあるのですが、例えば画面から呼ばれるものであったり、外部に公開するようなAPIである場合は、必ずしも使いやすいとは限りません。それは、APIが利用しやすいのと、DBのスキーマとして適切かというのは、両立しない時があるからです。例えばデータ更新のバッチ処理でAPIを呼び出すみたいな時は、DBスキーマに合わせるやり方は、けっこうあるかなと感じます。
【画面】
画面から呼ばれるAPIの場合は、画面の構成に合わせてAPI設計をすることが多いと思います。ただ、画面との結びつきが強すぎることに対しては、問題もあります。
以下の記事にあるような画面の変更時にAPIも修正が必要になったり、画面毎にAPIを作成したりすることになって、実装コストが膨らんでしまうといったリスクがあります。
【ドメイン】
DBスキーマでも画面に合わせても最適解でない、そんな時はドメインをベースにAPIを設計していくというのも手です。少しフワッとしてしまうのですが、以下の記事のように各APIのインターフェースを、ドメインモデルに合わせていく形になります。
個人的には、まずはドメインをベースにAPIを考えていくのが良いかなと思います。ただ、DBのスキーマや画面の構成の関係上ドメインに合わせるのが難しいという場合は、無理にドメインに合わせる必要までは無いかなと考えています。全ての要素をドメインで統一するのはコストもかかるし、システムとしてそれが最適でない可能性があるので、やはり要所要所でどうすべきかを考えていく必要がある気がします。
APIを考えるあたり、上記のどれか一つだけを考慮すればよいということは、あまり無い気はします。APIに求められる機能はなんなのかというのを鑑みて、このケースでは何に合わせるのが最善かを考えるように、私はしています。
