API はそのドキュメントの良し悪しに左右されます。素晴らしい API であっても、その使い方を知らなければ役に立たないことがあります。そのため、ドキュメントは API エコノミーでの成功にとって極めて重要となる可能性があります。しかし、読みやすく、操作が楽しく、利用者が成功できるようにする優れたドキュメントを作成し、維持することは非常に困難です。優れたドキュメントの作成には労力と忍耐が必要ですが、API の採用と保守性に直接的な影響を与えます。適切なAPI ドキュメントツールを選択することで、API のドキュメント作成は格段に管理しやすくなります。以前の記事では、優れた API ドキュメントの利点を詳しく説明しました。しかし、優れたドキュメントとは具体的に何を意味するのでしょうか？ 私たちは、あなたのチームがエンドユーザーに愛される優れた API ドキュメントを作成するのに役立ついくつかのベストプラクティスを詳細に説明しました。 しかし、その前に、1つの重要な質問を理解することが重要です...
API ドキュメントは誰のためのものですか？
API は、特定の業界の企業が直面する現実世界の問題を解決することを目的としており、ソフトウェア エンジニアによってアプリケーションに直接統合されます。そのため、API には潜在的な利用者が 2 種類あり、これらが API の利用と導入曲線に影響を与えます。
意思決定者
彼らはあなたの API サービスを評価し、開発チームがそのサービスを検討するのに時間を費やす価値があるかどうかを決定する人々です。彼らはあなたの API を使って、彼らの製品やサービス戦略における潜在的な課題を解決しようとしています。多くの場合、彼らはあなたの API を直接操作しませんが、組織がそれを利用する決定に影響を与える主要な連絡窓口です。意思決定者の例としては、CTO やプロダクトマネージャーが挙げられます。
ユーザー
これらの人々は、あなたの API を直接操作する人々です。彼らはあなたの API の詳細と、それが彼らのユースケースにどのように適用されるかを学ぶ必要があります。これは、あなたが公開する多くの、あるいはすべてのリソースを呼び出し、統合する方法を学ぶことを意味するかもしれません。彼らはあなたの API の持続可能性にとって重要です。彼らは分析的で、重要で困難なエンジニアリング問題に取り組み、時間が不足しています。したがって、あなたの API は使いやすく、これらのユーザーができるだけ早くあなたの API と成功裏に統合できるように、優れたドキュメントが必要です。API ユーザーの例としては、フロントエンド開発者とバックエンド開発者が挙げられます。 
API のドキュメントは、これら両方のペルソナに対応する必要があります。これは難しい作業ですが、これによりAPI ドキュメントが持続可能かつ完全なものとなり、長期的な成功と ROI を保証します。
APIドキュメントのベストプラクティス
API ドキュメントの対象者を理解したところで、次に優れた API ドキュメントに実際に何が必要なのかを理解する時です。
APIドキュメントの基本的なセクション
いくつかのセクションは、優れた API ドキュメントの基本となっています。これらのセクションは、優れたドキュメントのベースラインを形成し、API が想定される業界と顧客の種類に基づいて詳しく記述されるべきです。これらのセクションには以下が含まれます。
認証
これは、API の利用を開始するための認証スキームの使用に関する情報です。ほとんどの API には認証スキームがあり、利用者は API にアクセスする前に認証する必要があります。このセクションが適切に文書化され、ユーザーが API に対して認証を成功させるための手順が示されていることを確認してください。Bitly は簡潔な認証ドキュメントの素晴らしい例です。
エラーメッセージ
エラーメッセージは、エンドユーザーが API サービスを誤った方法で統合している場合にそれを伝えるため、重要です。エラーの標準を説明し、エンドユーザーがエラーを受け取った際にそれを克服する方法に関する解決策も提供してください。Mailchimp は、顧客が受け取る可能性のあるすべてのエラーコードを詳細に説明する良い仕事をしています。
リソース
API のリソースと、それらに関連するリクエストおよびレスポンスサイクルに注意を払ってください。リソースは API の中心となるコンポーネントであり、ユーザーは常にそれらとやり取りします。API が公開するすべてのリソースをリストアップし、顧客がそれらとどのように統合するかを理解してください。これにより、これらのリソースの下でのリクエストとレスポンスをより適切に文書化する方法を把握できます。
利用規約
これは、利用者と貴社との間の法的合意であり、利用者がサービスを理想的に使用する方法を定義します。ベストプラクティスとして API 制限を含め、利用規約も明記してください。利用者が API の使用方法と許可されるプラクティスを理解できるように、制約も明確に記載する必要があります。以下は、Spotify の API 利用規約の例です。
変更ログ
API の更新とバージョン、およびそれらが API ユーザーにどのように影響するかを詳細に記述します。これは、ユーザーが API の安定性を知り、効果的な API 呼び出しのために変更が必要かどうかを確認するのに役立ちます。以下は、GitHub の API 変更ログの例です。 API ドキュメント作成を開始する前に上記のセクションをマッピングすることは、テクニカルライターが重要な優先順位を把握するための良い方法です。
専門用語を避ける
API を扱う多くの人々は、あなたが使用するドメインや専門用語について詳しい知識を持っていない可能性があることに注意してください。ドキュメントは、「非常に技術的な」開発者層と、プロダクトマネージャーのような技術に疎い意思決定者の両方に対応する必要があります。テクニカルライティングチームが犯す大きな間違いは、読者が完全に技術的で、API の操作方法を完全に理解していると仮定することです。 ドキュメントは平易な英語で書き始め、すべてのリソースについて分かりやすいドメインの説明を記載してください。専門用語の使いすぎを避け、API や業界の初心者でも簡単に理解できる方法で記述してください。 もし技術的またはドメイン固有の専門用語がある場合は、その特定の項目を、これらの用語を説明する追加ドキュメントにリンクしてください。これにより、API 全体で明確性と完全性が確保され、ユーザーは特定の呼び出しが存在する理由を知ることができ、パラメータ、ヘッダー、レスポンスの詳細に迷いすぎることを避けられます。 この良い例はStripe の API ドキュメントです。そこでは、技術的な言葉を使わないように意図的に努力しています。ドメインベースの専門用語がある場合でも、その意味を説明する追加コンテンツによって補強されています。 YouTube の APIは、完全性と明確性で知られており、開発者が API の仕組みを簡単に理解できるようにしています。また、さまざまなリソースの実装に関するドキュメントに簡単にアクセスできる、優れたナビゲーション左パネルも備えており、私個人としては非常に有益だと感じました。
リクエストとレスポンスを大切に扱う
リクエスト・レスポンスサイクルのドキュメントには、それにふさわしい配慮をしてください。エンドユーザーがアプリケーションにサービスを統合しようとしている場合、利用可能な情報が多すぎることは決して問題になりません。そのため、リクエスト・レスポンスサイクルを詳細に記述してください。 API が提供するすべての呼び出しを、パラメーターとレスポンスのコンテキストとともに文書化してください。 レスポンスは、ユーザーが正しい軌道に乗っているかどうかを示すガイドであり、成功を助けるエラーメッセージによるガイダンスを提供します。API ユーザーは、成功した API 呼び出しから何を期待すべきかを正確に知る必要があります。サポートされているすべての形式で、完全なサンプルレスポンスボディを記述してください。XML や JSON のような形式だけでなく、HTTP ヘッダー、エラーコード、メッセージも考慮してください。 パラメーターとレスポンスの例も重要です。API が返すすべてのオブジェクトについて例を提供し、ユーザーが成功した API 呼び出しのために追加できるパラメーターの例も提供してください。 以下は、Stripe のエラーレスポンスに関する優れたドキュメントの例です。リクエストとレスポンスに関する優れたドキュメントのもう一つの素晴らしい例はInstagramです。
リソースでドキュメントを武装する
API を利用するユーザーが成功するために提供できる追加情報やリソースがあります。優れた API ドキュメントは、基本的なコンテンツや Swagger UI が生成するものを超え、ユーザーや見込み客が API をできるだけ早く成功に導くことを保証することです。ドキュメントには、次のような追加リソースを補足することができます。
入門ガイド
「はじめに」ガイドは、API の使用を迅速に開始する方法を詳細に説明しています。このガイドの重点は、ユーザーが可能な限り早く API を成功裏に利用できるように、この旅全体を通じて手厚くサポートすることです。Braintree の優れた「はじめに」ガイドの例は、彼らの API を統合し、操作する方法について素晴らしい概要を提供しています。
SDK とライブラリ
コードライブラリは、開発者がさまざまなリソースを迅速に呼び出すのに役立ちます。異なる言語で API を操作するための迅速かつ簡単な方法があることで、開発者は API をより快適に操作できると感じます。SDK は構築が難しく、ローンチに不可欠ではありませんが、API の採用を大幅に向上させることに貢献できます。あなたのビジネスモデルが公開されたオープン API モデルである場合、SDK を持つことは開発者コミュニティと関わる素晴らしい方法です。そのようなシナリオでは、開発者があなたの SDK と API に価値を見いだせば、それらを基盤にして構築したり、さらに多くのライブラリを追加したりする可能性が高くなります。Swagger Codegenプロジェクトは、チームが API ドキュメントから直接 SDK を迅速に生成するのに役立ちます。
インタラクティブコンソール
見込み客が API ドキュメントで読んだことを API コンソールで直ちにテストするように促しましょう。実験は強力であり、コンソールはユーザーの観点からの責任が限られているため、開始を容易にします。人々が API と対話できるコンソールまたはサンドボックス環境を作成することは比較的簡単な努力ですが、開発者が API の価値を視覚的に知るのに大いに役立ちます。多くの企業、例えばGitHubやMicrosoftは、彼らの API 提供物を試すためのインタラクティブコンソールを提供しています。
良いAPIドキュメントには労力がかかりますが、それだけの価値はあります。
私たちは常に、API ドキュメントが API の成長と成熟を先導する強力なツールであると信じてきました。それは、API を利用する際の優れた開発者エクスペリエンスの基盤です。 上記のヒントで、優れたドキュメントへの道のりがより簡単になることを願っています。 OpenAPI Specificationのような人気のあるオープンソース記述形式や、SwaggerHubのような商用プラットフォームは、チームがドキュメント作成プロセスを自動化し、API を利用する全体的な優れたエクスペリエンスに取り組むことを可能にします。 SwaggerHub の API ドキュメント作成機能はこちらで探索するか、無料でご自身でお試しいただけます。
ウェビナー：エンタープライズをAPIプラットフォームへ変革する教訓
あなたのデジタルトランスフォーメーションの取り組みは、ビジネスを正しい方向へ導いていますか？4月10日、私たちは無料ウェビナー「エンタープライズをAPIプラットフォームへ変革する教訓」を開催します。このセッションでは、ホスピタリティ、ローン組成、フィンテックの様々な組織と協力してAPIプラットフォームを開発・展開する中で学んだ教訓に焦点を当てます。これらの企業は、全体的なプラットフォーム戦略の一環として、APIファースト設計、連合型ガバナンス、API管理層を実装しました。何がうまくいき、何がうまくいかなかったのか、そして変革の取り組みを円滑に進めるためのヒントを探ります。議論されるトピック
- 内部再利用と活発なパートナープログラムを促進する効果的なAPIプログラムの開発
- 集中型ガバナンスと連合型ガバナンスの探索を含む、APIガバナンスを実装するための手法
- マイクロサービスとモジュラーソフトウェア設計が今日の企業の文化をどのように変えているか
- 優れたポータルと開発者サポートプロセスを開発することでAPIのオンボーディングと採用を増やす
- 企業に対するAPI中心のアプローチで変革の取り組みを加速するためのヒント
今すぐ登録 