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

先日登壇したイベントにて、仕事で協業したモバイルエンジニアから「Web APIのドキュメントに使われ方の想定が添えられていてありがたかった」とフィードバックをもらった。

具体的にはX post (以下、tweet) に添付した画像のような感じで、Web API (以下、API) が呼び出される画面・タイミングの想定、レスポンスの使われ方の想定などをUIのスクショとともに記述する、というもの。

API設計時にこういう使われ方の想定を添えると認識揃えやすくてありがたい、とモバイルエンジニアに喜ばれました#B43_techtalk pic.twitter.com/XLB3g6fCLZ
— ohbarye (@ohbarye) 2023年8月3日

他にもこんなのとか。

このことについて思ったよりもイベント内外で反響があったので書く。

ドキュメントの種類、やっていること

まず、文脈を補足しつつやっていることを詳しく書いてみる。

ここでいうAPIとは特定のクライアントしか利用しない、内部にしか公開していないAPIである*1。このようなAPIを開発する過程で2種類のAPIドキュメントを書いている。

RESTish APIのOpenAPIドキュメント
- 構造的にAPIの仕様を記述
- repositoryにコミットされるYAMLファイル
- ストック情報
プロジェクトの過程で記述するAPIドキュメント
- 非構造的にAPIの概要・レスポンス例・使われ方を記述。変更内容やその理由・背景を添えることもある
- Notionページであり、コードベースとは独立して存在
- フロー情報

tweetで言及したのは2のほうのドキュメントである。

そもそも「なんでOpenAPIと二重にドキュメント作ってるの？」みたいなツッコミがありそうなので先に回答しておくと、2つのドキュメントの目的・用途は大きく異なる。

OpenAPIのほうはストック情報。構造的に仕様を記述するもの。記述した仕様とコードの挙動が一致するかどうかのテスト自動化も行っている。これまでに書いてきた蓄積のうえに追記する。
tweetで言及したほうはフロー情報。「今回のプロジェクトで追加/変更するAPIの一覧と説明」のようにスコープを絞ったページを新たに追加する。一時的なコミュニケーションに役立てる一過性の情報。構造化する必要はなく意思疎通や意思決定の促進のために書く。

コミュニケーションツールとしてのフローAPIドキュメント

フロー情報のほうのドキュメントの必要性にもう少し言及すると、自分の場合は「自分がつくったAPIでUI上でのユースケースを満たせるか」を脳内検証するのを一義として書いている。

具体的には

💭クライアントは画面を開いた時に#GET v1/productsを呼んで商品一覧を表示。レスポンスのフィールドproducts[i].nameはそのまま、products[i].priceは,で区切って表示。ユーザーが購入ボタンを押したら#POST v1/ordersへproducts[i].idの配列を送って...

みたいに。この作業過程が「UIのスクショを貼って使われ方の想定を書く」にあたる。

成果物が結果としてクライアントサイドに役立つと企図してはいるが「この通りに使え」という意味ではなくて「こう使ったら仕様を実現できると思うけどどう？」ぐらいのノリ。

書いた後にはクライアントサイドの同僚にもレビューしてもらうので、想定質問や要議論ポイントも書く。過不足あれば当然修正する。

このような試行錯誤やコミュニケーションを行いたいという要求に対し、OpenAPIでは物足りない。

OpenAPIにはプロジェクトにスコープを絞ったような情報は基本的には書かない。加えて、画像を貼ったり図示したりとリッチな記述はできないし（できないと思っているけどやり方があれば知りたい）コミュニケーションツールとしてはかなり厳しい。OpenAPI編集を行うpull request上で議論を進めるプロジェクトも過去にあったが、あまりうまくいかなかった。

そう、構造化されたAPIドキュメントだけでは足りないから、やっている。

これはRESTishかどうかに関係なく、プロトコルやインタフェースによらず生じる課題だと思っているのだがどうか。