API設計をしたときにしくじったこと

API設計をしたときにしくじったこと

今、関わっているWebアプリケーションのAPIを設計する際に

しくじったことを列挙していくポエムです。

しくじり1 応答メッセージの基本形を決めずに作っちゃった

APIを使うクライアントも自分で作る状態だったので、とりあえず

行き当たりばったりで進めていった結果、共通のお作法が存在しない状態に

なってしまった。

しくじり2 HTTP応答コードだけでエラーを表そうとしてしまった

大抵は、応答コードだけでなんとかなります。ただし、更新時のバリデーション

エラーなど、何がどうエラーだったのかを返そうとすると、応答コードだけでは

全然足りません。そして、エラーの返し方を共通化しておかないと、APIによって

エラー発生時の応答が変わってしまい、クライアントを作る人が悲惨です。

しくじり3 業務よりのAPIと素のDB操作に近いAPIが混在しちゃった

これはしくじりなのかまだ決めかねているけれども、なんか微妙なのでしくじりに

しておきます。例えば、テーブルAとそれに紐付くBがあったとして、素テーブル

操作っぽいAPIだと、Aを全件取ってくる→Aをループして紐付いたBを取得する。

というような処理は割とよくあると思うのですが、これをAPIとして提供した。

性能問題が出るよりJOINして渡した方が良いだろうと。その結果、APIの数が

増えてしまい、どれ使ったら良いんだろう?と悩む状態になることがしばしば発生。

APIのシンプルさと実務的な側面をどうバランスさせるのかは非常に悩ましい。

美しさだけなら、シンプルなAPIだけ用意してあとはがんばれ!で良いのですが…