Web API設計時に使われ方の想定を添えると良い。けどより良いやり方を知りたい - valid,invalid

先日登壇したイベントにて、仕事で協業したモバイルエンジニアから「Web APIのドキュメントに使われ方の想定が添えられていてありがたかった」とフィードバックをもらった。 具体的にはX post (以下、tweet) に添付した画像のような感じで、Web API (以下、API) が呼び出される画面・タイミングの想定、レスポンスの使われ方の想定などをUIのスクショとともに記述する、というもの。 API設計時にこういう使われ方の想定を添えると認識揃えやすくてありがたい、とモバイルエンジニアに喜ばれました#B43_techtalk pic.twitter.com/XLB3g6fCLZ— ohbarye (@ohbarye) 2023年8月3日 他にもこんなのとか。 APIレスポンスの使われ方の想定を書いているようす このことについて思ったよりもイベント内外で反響があったので書く。 ドキュメントの

[ohbarye]

より良いやり方を知りたいです。切に〜

[turanukimaru]

OpenAPIの表現力が狭すぎる。画像を張り付けたりしたい。Springbootから生成するときに順番を指定したりしたいのに出来ないのももどかしい。そういや説明にURL書けるのかなやってみるか。

[ozmaLee]

これは良いね。

[yo_waka]

OpenAPIだと足りない、わかる

[yug1224]

最終成果物をつくるために「API利用指示書」みたいな中間成果物を作っていたことがあるが、それに近いなと感じた。Confluenceでスクショペタペタして赤枠加工していたのまで同じｗ

[fog-og-frog2]

めっっちゃわかるー最近遠ざかってるけど知りたいof知りたい。RestAPIで表現できることって基本ステートレス=文脈レスなのよね。でもAPIの前後には何かしらの繋がりがあるはずでそれを表現できる手段ってないよね…

[parasporospa]

Notionでなくdraw.io使ってるけど、スクショ貼ってコメント書くのは同じ

[nemoba]

詳細の段階でAPIと画面を紐づけてるので、概念の段階で情報モデルとUIの対応関係を作って、API仕様へのポインタとする。フロントエンドデザイナがそれを理解できるように広げる。工程と役割がいじれるなら。とか

[efcl]

NotionでAPIと画面の対応をまとめるコミュニケーション