先日登壇したイベントにて、仕事で協業したモバイルエンジニアから「Web APIのドキュメントに使われ方の想定が添えられていてありがたかった」とフィードバックをもらった。 具体的にはX post (以下、tweet) に添付した画像のような感じで、Web API (以下、API) が呼び出される画面・タイミングの想定、レスポンスの使われ方の想定などをUIのスクショとともに記述する、というもの。 API設計時にこういう使われ方の想定を添えると認識揃えやすくてありがたい、とモバイルエンジニアに喜ばれました#B43_techtalk pic.twitter.com/XLB3g6fCLZ— ohbarye (@ohbarye) 2023年8月3日 他にもこんなのとか。 APIレスポンスの使われ方の想定を書いているようす このことについて思ったよりもイベント内外で反響があったので書く。 ドキュメントの
![Web API設計時に使われ方の想定を添えると良い。けどより良いやり方を知りたい - valid,invalid](https://cdn-ak-scissors.b.st-hatena.com/image/square/92e56919514dd2aca214bdec9e72bf467935fc74/height=288;version=1;width=512/https%3A%2F%2Fcdn-ak.f.st-hatena.com%2Fimages%2Ffotolife%2Fo%2Fohbarye%2F20230806%2F20230806130156.png)