APIドキュメンテーションの重要性
APIは利用されてこそ価値があります。そのため、顧客や利用者がAPIをすばやく実装でき、その効果を得られるようにすることが重要です。残念なことに、実装が難しいため、本来の目的を果たせないAPIも多くあります。APIを構築する際には、開発者が接続や統合、デバッグを実施するために役立つ豊富な情報量を持つAPIドキュメントを用意するのはもちろん、ユーザが呼び出したとき（特に呼び出しに失敗したとき）に、関連データを返せるようにしておくべきでしょう。
APIドキュメントのレスポンスボディの体裁を整え、一貫性を持たせることは非常に重要です（復元・繰り返し・理解が、簡単にできるものが望ましい）。一方で、開発者にはステータスコードの使用など、呼び出しで発生した事象に関するクイックリファレンスも提供したほうが良いでしょう。また、エラーが発生した場合、顧客にエラー名だけを提示するのではなく、修正方法を含めた詳細メッセージを提供したいと考える開発者も多いと思います。
APIドキュメンテーションの作成は計画的に
APIを計画するとき、APIドキュメントのメンテナンス方法を知っておく必要があります。ほとんどのパブリックAPIにおいて、ドキュメンテーションがユーザビリティの核心であることが証明されており、これを軽視できません。ドキュメンテーションは手軽で簡単な作業に見えるかもしれませんが、ほとんどの企業にとって、APIのメンテナンスにおける最も大きな課題の一つだと言えます。
ドキュメンテーションは、APIの成功を左右する重要な要素です。有効で分かりやすいドキュメントはAPIの実装を円滑にします。一方、「紛らわしいドキュメント」または「同期していないドキュメント」「不完全なドキュメント」「複雑なドキュメント」は、APIの開発者と利用者を迷宮に導きます。その結果、不満が大きくなり、競合のソリューションに乗り換えられてしまうことでしょう。
ドキュメントは体裁に一貫性があるだけでは不十分で、APIの機能（の説明）に整合性を持ち、最新の変更・更新が反映されていなければなりません。また、経験豊富なドキュメントチームにより、開発者向けに分かりやすく作成されている必要があります。最近まで、ドキュメンテーション・ソリューションには、高価だが専用のサードパーティシステムやCMS（既存システムやオープンソース（DrupalやWordPressなど））を必要としていました。高価なAPIドキュメント専用のソリューションは、ドキュメントの体裁に一貫性を持たせることはできます（CMSでは不可能）。しかし、コードの整合性を確保するためには、開発者の手作業に依存しなければなりません（コードから開発した場合は特に）。
しかし、RAMLのようなオープンスペックの浸透とコミュニティの拡大により、APIドキュメンテーションは大幅に容易になりました。ドキュメントチームが、コードを解析したり、開発者にインラインで説明を記述してもらうことなく、API仕様に準拠した説明的なドキュメントを作成・提供することが可能です。すべてのコードパラメータ／サンプルはすでに含まれているため、ドキュメントへの移行が簡単に行えるのです。これらの仕様を利用し拡張するAPIドキュメンテーションのSaaS企業が爆発的に増えており、効果的なAPIポータルやドキュメントの作成が、かつてないほど簡単かつ安価になりました。
優れたAPIドキュメントの書き方
Good documentation should act as both a reference and an educator, letting developers quickly obtain the information they are looking for at a glance, while also reading through the documentation to glean an understanding of how to integrate the resource/method they are looking at. As such, good documentation should be clear and concise, but also visual, providing the following:
- メソッド／リソースの効果についての明確な説明
- 警告やエラーなど重要な情報を開発者と共有するためのコールアウト
- 関連するメディアタイプのボディを含むサンプルコール
- 対応している言語のリスト
- リソースやメソッドで使用されているパラメーターのリスト（※リストには「タイプ」「特殊なフォーマット」「ルール」「必須」などを記述すべき）
- メディアタイプのボディを含むレスポンスのサンプル
- 複数言語のコード例（PHPのCurlやJava、.Net、Rubyなど必要なすべてのコードが含まれる）
- 各言語でのリソースやメソッドへのアクセス方法を示すSDKの例（SDKが提供されている場合）
- APIコールを試すためのインタラクティブ・エクスペリエンス（API Console、API Notebook）
- コード例に関するFAQとシナリオ
- 他のリソースへのリンク（別の例やブログなど）
- ユーザがコードを共有・議論できるコメント欄
- その他のサポートリソース（フォーラム、問い合わせフォームなど）
APIドキュメンテーション・ツール
スペック駆動型開発では、APIドキュメントのソリューションの構築のために、高価で複雑なベンダーに頼ったり、WordPressやDrupalなどのCMSでその場しのぎ的な解決策を利用する必要はありません。RAMLやSwagger、API Blueprintなどの仕様には、強力で頼りになるオープンコミュニティが存在しており、そこでプレビルドのドキュメントツールが提供されています。これはスペック駆動型開発の大きなメリットとなっています。
各コミュニティで独自のツールセットが提供されていますが、ここではRAMLコミュニティで利用できるツールについて紹介します。RAMLコミュニティでは、Java、Ruby、PHP、Nodeなど複数の言語のためのパーサーに加え、APIドキュメント管理のための豊富なスクリプトがすでに構築されており、API ConsoleやAPI Notebookといったインタラクティブな環境が用意されています。これらのツールにより、上記の「ReadMe.io」や「Constant Contact」「Twilio」の例にあるようなドキュメントを最低限の作業で提供することが可能です（もちろんインストールとRAMLの定義は必要となります）。
多くの企業がAPIの価値の高まりを認識し、何百ものAPIの開発をしています。これらAPIを、利用者でもある開発者が簡単に発見および理解できるような方法で、適切にAPIを公開することは、企業のAPIプログラム全体の成否を左右すると言っていいほど重要です。優れたドキュメンテーションは、この成功のための重要な役割を担っています。