開発者が初日から従うことができる明確なAPIドキュメントを作成します

ほとんどのAPIドキュメントが失敗する理由

エンドポイントは記述されているものの、実際に人々を妨げる部分、つまり認証方法、現実的なリクエストの見た目、エラーの意味、そしてそれに対する対処法が省略されています。読者はサポートチケットを開くことになり、これはドキュメントが存在する目的であるコスト削減に反します。

私の書き方

記憶からではなく、ソースから。私はルート、バリデーションレイヤー、エラーハンドラーを読み込み、実際の認証情報でAPIを自分で呼び出します。ドキュメント内のすべての例は、私が作成したリクエストと私が受け取ったレスポンスです。作成されたペイロードや、エンドポイントが返すことのないステータスコードはありません。

ドキュメントの内容

• 認証：トークンの取得、更新、セッション中に期限切れになった場合の挙動。
• パラメータ、完全なリクエスト例、実際のレスポンス形式を含むすべてのエンドポイント。
• 各エラーコードを原因と修正にマッピングするエラーリファレンス。単にメッセージを繰り返すだけではありません。
• 新しい開発者がゼロから10分以内に成功した呼び出しを行うための入門パス。
• レート制限、ページネーション、ウェブフック、冪等性が、実際に適用される場所で説明されています。

フォーマット

リポジトリ内のMarkdown、OpenAPIまたはドキュメントサイト用に構造化されたもの — 実際に保守する方。ユーザーが尋ねる言語でのコードサンプルは、実行して検証済み。Postmanまたは同様のコレクションが必要な場合は含まれます。

必要なもの

リポジトリへのアクセスまたはOpenAPIファイル、テスト環境用の動作する認証情報、およびサポートチームが回答にうんざりしている質問。これらの質問がアウトラインとなります。

含まれていません

マーケティングコピー。これはソフトウェアが何をするかを正確に文書化するものであり、ランディングページは別の専門分野です。

納期とコミュニケーション

最初の完全なドラフトは通常1週間以内に届き、お客様のサポートチームが繰り返し回答している質問と照らし合わせてレビューしていただきます。洗練されていても間違っているものを納品するよりも、エッジケースを知っているエンジニアに早期に修正してもらう方が良いと考えています。最終ドキュメントのすべての例は、お客様のAPIに対して実行されているため、そこに願望的なものは何もありません。