あなたのAPIドキュメントには47個のエンドポイントがリストアップされている。それぞれにHTTPメソッド、パス、リクエストボディ、レスポンススキーマが記載されている。完全で、正確で、そしてまったく役に立たない。
なぜか？ なぜなら、あなたのドキュメントにたどり着いたとき、私はたいていエンドポイントの一覧が欲しいわけではないからだ。
私はタスクを完了したいのだ。
顧客を作成し、支払い方法を紐付け、サブスクリプションを開始し、Webhookを処理し、障害から復旧し、安全にテストする方法を知りたいのだ。
エンドポイントリファレンスは必要だ。しかし、それはプロダクトではない。
リファレンスはオンボーディングではない
リファレンスページが答えるのは：
- どんなパスが存在するか
- どんなメソッドを受け付けるか
- どんなフィールドが許可されているか
- レスポンスがどのようなものか
オンボーディングが答えるのは：
- 最初に何をすべきか？
- これらの呼び出しはどの順序で行われるか？
- 何が失敗しうるか？
- 何を保存すべきか？
- 本番環境を壊さずにテストするにはどうすればよいか？
ドキュメントにリファレンスページしかない場合、開発者は生の部品からワークフローをリバースエンジニアリングしなければならない。
だからこそ、「完全な」ドキュメントでも使い物にならないと感じられるのだ。
開発者が実際に持つジョブから始めよう
ほとんどのAPIにおいて、本当のドキュメントはタスクパスから始めるべきだ：
- リクエストを認証する
- 最初のリソースを作成する
- リソースを安全に更新する
- Webhookをリッスンする
- 失敗した操作をリトライする
- テストモードから本番環境に移行する
そして各タスクからエンドポイントリファレンスへリンクを張る。
ガイドは開発者の目標から始まり、動作するパスを示し、例を含み、正確なエンドポイント詳細へのリンクを提供する。
順序が重要だ。最初のページが巨大なリファレンステーブルであれば、読者に一人でメンタルモデルを構築させることになる。
孤立した呼び出しではなく、完全なパスを示す
悪いドキュメントは完璧なリクエストを1つ示す：
POST /customersより良いドキュメントはシーケンスを示す：
- 顧客を作成する。
- サブスクリプションを作成する。
- 返されたIDを保存する。
- 確認用のWebhookをリッスンする。
- 失敗とキャンセルの状態を処理する。
このシーケンスこそ、開発者がインテグレーションをリリースするために必要なものだ。
さらに良いのは、ステートマシンの形状を含めることだ：
エラードキュメントはインテグレーションの一部である
本格的なAPIは、何かが失敗したときに開発者に何をすべきかを伝える。
次のようなところで止まってはいけない：
{ "error": "invalid_request" }次のことをドキュメント化する：
- リクエストをリトライしても安全か
- 操作が部分的に成功した可能性があるか
- どのエラーがユーザーのアクションを必要とするか
- どのエラーがオペレーターのアクションを必要とするか
- サポートに送るべきIDは何か
- Webhookが信頼できる情報源か
ここでAPIドキュメントは信頼のインフラストラクチャとなる。
本番環境の現実に合った例を使う
本番ワークフローがおもちゃでないなら、例もおもちゃであってはならない。
悪い例：
{ "name": "John" }より良い例：
{
"externalId": "acct_123",
"email": "operator@example.com",
"plan": "studio-audit",
"metadata": {
"source": "route-finder",
"campaign": "content-engine"
}
}より良い例は、命名、メタデータ、冪等性、属性情報を教える。開発者が実際のものを作るのに役立つ。
本番環境前のチェックリストを追加する
実際のビジネス影響があるすべてのAPIには、リリースチェックリストを含めるべきだ。
このチェックリストはリファレンスを置き換えるものではない。リファレンスを使い物にするものにする。
ドキュメントをテスト可能にする
最高のAPIドキュメントはシステムに十分近いため、システムが変わると失敗する。
それは次のことを意味する：
- 型付きスキーマから生成された例
- CIで検証されるリクエスト例
- ルートハンドラに対してチェックされるOpenAPI出力
- ビルドごとにチェックされるドキュメントリンク
- 公開ワークフローに対するコントラクトテスト
ドキュメントがコードから遠く離れて手動でメンテナンスされていると、乖離が生じる。乖離が生じると、開発者はドキュメントを信頼しなくなる。
私が好む構造
本格的なAPIの場合、私は次のIAを出荷する：
- はじめに：APIが何をするか、何を構築できるか。
- クイックスタート：1つの完全なハッピーパス。
- 認証：キー、スコープ、ローテーション、ローカルセットアップ。
- コアワークフロー：タスクベースのガイド。
- Webhook/イベント：配信、リトライ、シグネチャ、リプレイ。
- エラー/リトライ：何が失敗したか、どう対処するか。
- リファレンス：エンドポイントレベルの詳細。
- 本番チェックリスト：リリース時のガードレール。
- 変更履歴：破壊的変更と移行ノート。
これは過剰ではない。これこそ、セールスエンジニアが隣にいなくても誰かがインテグレーションできるようにするものだ。
