APIドキュメント

APIドキュメントとは？

APIドキュメントとは、APIの利用方法や統合方法を人が理解しやすい形でまとめた説明資料です。

APIドキュメントには、利用可能なエンドポイント、メソッド、リソース、認証プロトコル、パラメーター、ヘッダーに関する詳細情報に加え、一般的なリクエストとレスポンスの例が含まれます。質の高いAPIドキュメントは、プライベートAPI、パートナーAPI、パブリックAPIの開発者体験を向上させるだけでなく、それぞれのAPIに固有の価値ももたらします。たとえば、プライベートAPIのドキュメントはチーム間のコラボレーションを促進し、パブリックAPIのドキュメントはリーダーがサードパーティAPIの想定ユースケースを理解し、自社のビジネス目標の達成に役立つかどうかを判断しやすくします。APIドキュメントを重視するチームでは、APIの採用率向上、サポートチケットの削減、さらにパブリックAPIの場合は収益の増加といった成果が見られる傾向があります。

ここではまず、APIドキュメントがAPIファーストの世界で果たす役割について説明します。次に、APIドキュメントを構成する主要な要素とベストプラクティスを紹介します。最後に、Postman APIプラットフォームがどのように提供者によるAPIドキュメント作成を支援し、利用者の成功につなげているのかを見ていきます。

なぜAPIファーストの世界でAPIドキュメントが重要なのか

APIファーストとは、APIを通じて提供される社内外のサービスを組み合わせてアプリケーションを設計、構築する開発モデルです。このアプローチにより、複雑に連携するマイクロサービス群を基盤とした高性能なアプリケーションを構築できるだけでなく、APIをサードパーティの利用者向けに有料の製品として提供するAPI-as-a-Product戦略も支援できます。そのため、多くの組織がAPIファースト戦略を採用し、ビジネス目標の達成につながる高品質なAPIを体系的に開発しています。

APIドキュメントは、プライベートAPIとパブリックAPIのどちらにおいても、その成功を支える重要な役割を果たします。たとえば、社内向けAPIのドキュメントはチーム間のコラボレーションを促進し、コードの重複を減らすとともに、新入社員のオンボーディングを効率化します。これにより、すべてのチームが優れたソフトウェアをユーザーに提供するという共通の目標に向けて、効率的に業務を進められるようになります。一方、パブリックAPIのドキュメントは、利用を検討している利用者がAPIを理解し、実際に試せるようにすることで、採用の拡大、ひいては収益の向上につながります。実際、Postmanの『State of the API Report』では、サードパーティAPIとの統合を判断する際に、リーダーが重視する要素の1つとしてドキュメントが上位4項目に挙げられています。

代表的なAPIドキュメントの種類

APIドキュメントにはさまざまな種類があり、それぞれが利用者によるAPIの効果的な活用を支援する重要な役割を担っています。代表的なものとして、次の4種類があります。

• リファレンスドキュメント：一般的に、各エンドポイントのメソッド、パラメーター、サポートされているデータの型などの詳細情報を提供します。また、それぞれのエンドポイントが何を実行するためのものかを、わかりやすい言葉で説明します。
• サンプルとコードサンプル：一般的なAPIリクエストとレスポンスの例を提供します。複数のプログラミング言語でサンプルが用意されることも多く、利用者がAPIの動作や期待される結果を理解するのに役立ちます。
• リリースノート：新機能、バグ修正、セキュリティパッチなど、APIに加えられた重要な変更に関する情報を提供します。変更内容によっては利用者自身のコードベースに影響を与える可能性があるため、リリースノートは重要な情報源となります。
• チュートリアル：APIの利用方法を段階的に説明する形式のドキュメントです。多くの場合、APIがサポートする特定のユースケースに焦点を当てており、認証など利用開始時に必要となる一般的なワークフローについても解説します。

利用規約

パブリックAPIのドキュメントには、利用規約を含める必要があります。利用規約は、利用者によるAPIのデータや機能の不正利用を防ぐための法的契約です。また、一定期間内に利用者が実行できるAPIコール数を定めるレート制限に関する情報も記載する必要があります。エンドユーザー向けサービスの停止につながる可能性があります。レート制限は、サービス拒否（DoS）攻撃や、APIのパフォーマンスに悪影響を及ぼすその他のアクティビティからAPIを保護するのに役立ちます。レート制限を超過した利用者は、一時的に追加のAPIコールを実行できなくなり、その結果、エンドユーザー向けサービスの停止につながる可能性があります。

• Understand the API: Anyone who is writing API documentation needs to not only understand the API's purpose, but also be familiar with its endpoints, methods, parameters, accepted data types, and authentication mechanisms. This will help ensure that the documentation is accurate and complete.
• Know your audience: API documentation is consulted by a wide range of audiences that may have different levels of technical knowledge. It's therefore important to identify your primary audience—and understand their needs—to ensure your documentation is useful.
• Provide detailed instructions for the most common use cases: While you should strive to thoroughly document the API's complete functionality, you should pay special attention to the most common use cases. Additional details, such as code samples and example requests, will help consumers get up and running with these use cases quickly.
• Review, test, and verify the documentation: Everyone makes mistakes, so it's critical to thoroughly test your documentation before publishing it. This process should involve a thorough walk-through of every use case and request, as well as an additional review by a stakeholder who was not directly involved in the documentation writing process.
• Continuously update the documentation: APIs evolve quickly, and outdated documentation can confuse consumers and erode their trust. It's therefore essential that you methodically review your documentation whenever you ship new code—and make updates as necessary.