APIドキュメントは、API と同じくらい重要であり、オープンソースや有償の製品をユーザーが学び、理解し、使うことがいかに簡単であるかを確定するものです。本記事では、有名なツールから Integrate.ioがオススメする API ドキュメント８選をご紹介します。APIドキュメントを作成する際に、これからご紹介する例をぜひご参考にしてください。
それぞれのAPIドキュメントの例について知っておくべき重要なポイントは以下の通りです：
- Twilio：
- ヒント、チュートリアル、ベストプラクティスを含む、明確で構造化されたドキュメント。
- 左側メニューの簡単なナビゲーションと、複数のプログラミング言語の包括的なコード例。
- Slack：
- 明確な次のステップと専門用語の少ない初心者向けのコンテンツ。
- メニューベースのナビゲーション、広範な説明、重要なポイントを説明するためのスクリーンショット。
- Google Maps API：
- 親しみやすく読みやすい3段組レイアウトのドキュメント。
- シンプルなナビゲーション、ポピュラーなドキュメントのリスト、ベータ版の機能を示すフラスコのマーク。
- マイクロソフト：
- 検索可能なディレクトリとアルファベット順のリストを持つ広範な技術文書。
- Microsoft Learnブログによる追加情報。
- Vimeo
- Google Maps APIと同様のレイアウトで、3カラムのテンプレート。
- 詳細なGetting Startedセクションがあり、初心者に最適。
- Stripe
- すっきりとしたデザインで、明確で整ったドキュメント。
- 簡単なナビゲーション、クイックスタートガイド、トピック間のリンクがある。
- SendGrid：
- トピックや用語集へのリンクがあるシンプルでわかりやすいドキュメント。
- ドキュメント内のコードをテストするためのインタラクティブな機能。
- PayPal：
- トピック、特集リソース、サポートページへのリンクがあるドキュメント。
- 変更履歴やリリースノートを含めることで、変更を簡単に追跡できる。
1. Twilio
[参照：https://www.twilio.com/docs/usage/api]
Twilioの API ドキュメントは、その製品のすべての機能に関するさまざまなドキュメントをリストアップした「イントロページ」で始まっており、そのドキュメントのうち一つをクリックすると、画面左端にトピックとサブトピックがリストアップされた「メニュー」のある別ページが表示され、必要なコンテンツが簡単に見つかるようになっています。例えば、イントロページで「SMS」をクリックすると、SMSのページが表示され、ここでは「Getting Started（はじめよう）」 や 「API Reference（API リファレンス）」など、左側のメニューにリストされたトピックを見つけることができます。また、各トピックの下には、「How to work with your free Twilio account（Twilio 無料アカウントのご利用法）」のような一連のサブトピックがあります。
このAPI ドキュメントの例では、Twilioのdocsは明確でよく練られています。ヒント、チュートリアル、ユースケース、ベストプラクティスがわかりやすく書かれており、製品の機能をナビゲートするのに役立つスクリーンショットも掲載されていますね。
各サブテーマには、膨大な量の情報が詰め込まれています。上のスクリーンショットでは、Programmable SMS APIを使ってシンプルなSMSをPOSTするサンプルコードに、Node.js、C#、PHP、Ruby、Python、Java、Curl、その他のプログラミング言語用のコードと、JSON APIレスポンスのサンプルが含まれていることに注目してください。ユーザーは、コーディング言語を選択した後、ワンクリックでコードをコピーして、アプリケーションでコードを使い始めるといいでしょう。
2. Slack
[参照： https://api.slack.com/authentication]
ユーザードキュメントを書くときに、読者の存在を忘れないことが重要ですが、そのドキュメントを「Developer docs and guides（デベロッパー向けドキュメントおよびガイド）」と呼んでいるSlack では、ユーザーの中に初心者がいることを認識し、そういった読者を念頭に置いてより基本的なコンテンツが書かれています。特徴は以下の通りです：
- 各サブトピックのタイトルの下にある【難易度】のラベルで、ユーザーはドキュメントのどの部分を対象としているのかを理解できる。
- 新規ユーザーを設定プロセスに導くために、プロセスの次のステップが明確にラベル表示されている。
- 初心者に特化したコンテンツでの、より少ない専門用語でより充実した説明。複雑な情報は、箇条書きによって、より小さな纏まりとして噛み砕かれている。
ただこのスタイルは、このAPI ドキュメントの例の全ページでは継続されていないことに気づくでしょう。この『admin.apps.approve』メソッドのような参照ページでは、Slackは事実に忠実で、情報を探している経験豊富なデベロッパーが読者である可能性が高いことを認識しているのです。
Twilioと同様、Slackのドキュメントには、画面左端にトピックとサブトピックが一覧表示される「メニュー」があり、必要な情報に簡単にアクセスすることができます。また、多くのページには、重要なポイントを説明するスクリーンショットが掲載されており、この製品のさまざまな機能を学ぶことができます。
さらに読む： A Complete Guide to API Generation
3. Google Maps API
[参照： https://developers.google.com/maps/documentation/javascript/adding-a-google-map]
Google Maps APIのドキュメントは、Googleネットワークで見かける他のページと似たような外観をしており、白い背景と有名なフォントで構成されたこのドキュメントは読みやすく、 すぐに馴染めます。Google Maps API に必要な情報を探すのは簡単です。メインページの３列からなるレイアウトは、地図、ルート、場所のドキュメントを探すためのオプションがユーザーに提供されており、最もよく使われるドキュメントは、ヘルプやサポートリンクと同様にメインページにリストアップされています。
各トピックのページでは、左端に他のトピックの概要が表示され、それによってナビゲーションが簡単になります。また、右端のカラムは、ユーザーが読んでいる記事のコンテンツリストで、画面の中央に表示されます。
Google APIのドキュメントには、現在ベータモードの機能を表すフラスコマークなど、他にもいい工夫がいくつかされていますが、以前あった【ライトテーマ】から【ダークコードテーマ】に切り替えられる機能は、現在は利用できません。
4. Microsoft
[参照：https://docs.microsoft.com/en-gb/]
企業が大規模なドキュメントを作成する場合、ナビゲーションは１つのドキュメントの中から正しい記事を探すだけでなく、数十、数百のさまざまな情報の中から正しい記事を探すことに発展していきます。
例えば、マイクロソフトには、デベロッパーがアクセスできる膨大な種類のテクニカルドキュメント（技術文書）がありますが、そのディレクトリで、ユーザーが必要な情報に素早くドリルダウンしやすくなっており、そのドキュメントは、マイクロソフトでは『Learn』と呼ばれています。
Microsoft Learnの優れた機能として、以下のようなものがあります：
- 各ページに表示される検索バーでドキュメントを検索する機能
- ドキュメントトピックをアルファベット順に並べた製品ディレクトリ
- ドキュメント内のトピックに関する追加情報を提供する『Microsoft Learn』 のブログ
5. Vimeo
[参照： https://developer.vimeo.com/api/guides/start]
Vimeoのドキュメントは、一見 API ドキュメントの他の例、特にGoogle Maps APIとよく似ているように見えます。各トピックページには、３列のテンプレートがあり、左側にドキュメントのトピックがリストされたメニュー、真ん中にドキュメントそのもの、そして右側にその記事のコンテンツリストがあります。
ドキュメントの中で最も有用な部分のひとつが、『Getting Started Guide（入門ガイド）』であり、このセクションは、製品を初めて使う新規ユーザーや未経験のユーザーに対して、ドキュメントの枠を超えてサポートするものです。
Slackと並んで、Vimeoもまた、特に「Getting Started（はじめる）」のセクションを通じて、初心者に素晴らしいエクスペリエンスを提供するビジネスの一つなのです。
Vimeoには、以下のような特徴があります：
- Vimeo SDK の設定、アクセストークンの生成、最初の API 呼び出しなど、基本的な操作の一つ一つの説明がシンプル
- RESTなど、初心者が理解しにくい用語もわかりやすく解説。
- デベロッパー用ツールの使用に関するベストプラクティス
- 初心者にとって明確な「次のステップ」と、それによるワークフローのスピードアップの実現
ビジネスのドキュメントが社内向けで、現在のチームが経験豊富であったとしても、将来のチームメンバーを受け入れるために『入門ガイド』を作成することをお勧めします。
さらに読む：5 Best API Documentation Tools
6. Stripe
[参照： https://stripe.com/docs/api/authentication]
Stripe の API ドキュメントは Twilio と同じフォーマットで、同様に優れたエクスペリエンスを提供します。読みやすいクイックスタートガイドや素晴らしいナビゲーション、そしてデベロッパーが知らなければいけないであろう事柄が全て明確に説明されています。
Stripeの最大の強みは、ドキュメントの表示方法です。そのデザインは明快で、フォーマットも整っており、膨大な情報を提供してもすっきりとした印象を与えることができます。このデザインによって、Stripeを利用するデベロッパーは素晴らしいエクスペリエンスを生み出すことができます。
ナビゲーションに関しては、デベロッパーは画面左上の検索バーからいつでもドキュメントのトピックを検索することができます。また、各ドキュメントには他のトピックへのリンクがあり、それによってデベロッパーは、Stripeについて学ぶ際にページ間を行き来することができます。
7. SendGrid
[参照：https://sendgrid.com/docs/api-reference/]
SendGridのメインドキュメントページで最初に気がつくのは、そのシンプルさでしょう。ドキュメントのトピック、注目のリソース、注目の用語集へのリンクが表示されており、SendGridの各ドキュメントページは、６言語のうちの１つで見ることができます。
インタラクティブな機能により、デベロッパーはドキュメントを離れることなくコードをテストすることができ、それによってユーザーは物事を試したり、その動作を学びやすくなります。その好例が SendGrid のAPIドキュメントです。ユーザーは API キーを入れてから、コードをテストし、レスポンスを得ることができ、コードは編集可能なので、ユーザは変更を加えて、その変更がどのような効果をもたらすかを確認することができます。
8. PayPal
[参照：https://developer.paypal.com/docs/release-notes/release-notes-2020/#]
API ドキュメント８選のトリを務めるのは、PayPal Developer、またはPayPalが『ドキュメント』と呼ぶものです。そのメインページには、ドキュメントのトピックへのリンク、注目のリソース、さらに質問があるユーザーのためのサポートページへのリンクがあります。
新機能へのドキュメントの追加や、廃止された機能のドキュメントの削除やフラグ立てなど、API ドキュメントをメンテナンスすることで、デベロッパーにとって有益なリソースを確実に提供し続けることができます。
最近何が変わったのか、ユーザーが簡単に確認できるように、PayPal が REST API 用に公開しているような変更履歴やリリースノートを含めるといいですね。
PayPal の他のドキュメントも同様に便利です。このリストの他の API に比べるとトピックは少ないですが、左側のメニューの HTML カラムにドキュメントのトピックがリストアップされているので、必要な情報はすべて見つけることができます。そして２番目のメニューには、サブトピックが表示されます。
さらに読む： 7 Tips for Designing Great API Documentation
よくある質問：最高のAPIドキュメントの例
これらのAPIドキュメントにはどのような共通点がありますか？
Twilio、Slack、Google Maps APIなど、これらのAPIドキュメントのほとんどは、画面の左側にトピックとサブトピックをリストした明確なメニューを備えており、ナビゲーションがわかりやすいです。また、理解を助けるために様々な言語でのコードサンプル、理解しやすいガイド、スクリーングラブも含まれています。
これらのドキュメントは、開発者のさまざまなレベルにどのように対応しているのだろうか？
SlackやVimeoのようなプラットフォームでは、コンテンツを難易度別に区別し、初心者にはあまり専門的でない言葉を使用しています。経験豊富な開発者向けには、より事実に基づいた技術的なドキュメントで具体的な詳細や高度な機能に焦点を当てています。
これらのドキュメントにはインタラクティブな機能はありますか？
はい、SendGridのように開発者がドキュメント内で直接コードをテストできるインタラクティブな機能を提供しているドキュメントもあり、効果的な学習ツールを提供しています。
APIドキュメントはどのようにナビゲーションや検索を支援しますか？
MicrosoftやStripeのドキュメントのように、これらのドキュメントの多くは検索バーとよく整理された製品ディレクトリを備えており、ユーザーは必要な情報を素早く見つけることができます。
これらの文書には、初心者向けにどのような特別な機能がありますか？
初心者向けには、簡単なステップバイステップの説明、専門用語の明確な説明、ベストプラクティスといった特徴があります。VimeoやSlackは、このような初心者向けのコンテンツを提供しているプラットフォームの顕著な例です。
これらのドキュメントは、アップデートや変更についてどのようにユーザーに情報を提供しているのでしょうか？
PayPalのドキュメントに見られるように、Changelogやリリースノートを維持することは一般的なプラクティスです。このアプローチにより、ユーザーは新機能、非推奨機能、その他の変更に関する最新情報を得ることができます。
ドキュメントの多言語サポートはありますか？
はい、SendGridのようなドキュメントの中には、多言語でコンテンツを提供しているものもあります。
ドキュメントの「はじめに」ガイドの重要性は何ですか？
「入門ガイド」は、特に新規ユーザーにとって非常に重要です。初期セットアップや簡単なAPIコールを含む、製品の基本的な紹介を提供し、学習プロセスをスピードアップします。
Integrate.ioを使ったAPIドキュメントの管理方法
このような API ドキュメントの例から、API を適切にドキュメント化することがいかに重要であるかがわかります。Integrate.io は、エンタープライズグレードの API-as-a-Service（サービスとしてのAPI） プラットフォームで、コーディングの経験がなくても、完全にドキュメント化された REST API を速やかにに作成することができます。
特徴は以下の通りです；
- インタラクティブなドキュメント - Integrate.io は、Swagger が速やかなテスト、簡単な立ち上げ、すぐに使用開始が可能であることから、Swagger を使って完全にインタラクティブなドキュメントを作成します。
- 数分でのAPI 作成 - コーディングしない人でも数クリックで API を作成できるため、その分デベロッパーは他のプロジェクトに取り組むことができます。
- API の一元管理 - 使いやすい 1 つのプラットフォームで、 API をすべて作成、管理、ドキュメント化できます。
- シンプルなAPI生成 - SQL Server、MySQL、その他のデータソースのためのREST API を瞬時に作成します。
新しい API を作成すると同時に、完全にインタラクティブなドキュメントを自動的に作成しませんか。Integrate.ioの14日間無料トライアルをぜひご体験ください。
