これは雑多なメモです*1。
Webサービスを作るぞ、となったときにサーバサイドアプリケーションはGraphQLなりRESTなりのAPIを提供し、クライアントサイドアプリケーション（Webフロントエンドアプリだったりスマホアプリだったり）はそのAPIを呼ぶ。という責務分担をすることが多い気がしている。
そうなった際の責務分担の境界は「GraphQLなりRESTなりのAPI」であることに間違いはない気がしている。
それらのAPIドキュメントが完璧に書かれていれば、理屈の上ではサーバサイドとクライアントサイドのアプリケーションは相互に独立して開発を進められる。
完璧なドキュメントなんて存在しないし、理屈通りにはいかないけれど、それを志向はしたいと常々思っている。
そういう志向においては「APIドキュメントの書き具合」はどのくらいにするのがいいのだろうか。
仕事で開発しているWebサービスについての思案なので以下のようなものになる。
理想はエンドユーザーに提供するAPIのドキュメントのような全てが網羅されている状態だろう。無限の工数があればそうしたいですね。
そんな手間暇をかけるのは現実的ではないので、外から見た振る舞い、外部仕様を丁寧に書く、程度のポリシーで暮らしている。自分はAPIを提供する側だけれど、呼ぶ側としてこのドキュメントをみて迷わずに呼び出せるか？ イラつきはしないか？ を考える。
丁寧に書いていると、自分が実装するときに参考になるのもよい。
外部仕様書として見ると、サーバサイドクライアントサイドとの境界だけでなく、要件との境界、突合せもできて便利。
なので、現実的な落としどころは「外部仕様」を書くように心がける辺りじゃないかな、って思っている。
永遠のTODO ここに例が書かれる
そんな感じ！
*1:普段社内のナレッジベースに書いてるような内容だけれど、別に社外秘ないしブログに書いてしまってもいいだろう
