Hello there, ('ω')ノ
APIは通常、開発者がその使い方や統合方法を理解できるように文書化されています。このAPIドキュメントには、大きく分けて人間向けと機械向けの2種類があります。
1. 人間向けのAPIドキュメント
これは開発者がAPIの使用方法を理解しやすいように作成されたものです。具体的には、次のような情報が含まれます。
- エンドポイントの説明
APIの各エンドポイントとその機能の概要。 - リクエストとレスポンスの例
実際のリクエストと、それに対するレスポンスのサンプル。 - 認証情報
APIキー、OAuth、JWTなど、APIを利用するために必要な認証方法。 - エラーハンドリング
発生しうるエラーコードと、その対処方法。
このような情報は通常、公式サイトや開発者向けのポータルで公開されており、Swagger UI、Postmanコレクション、Redocなどのツールを使って提供されることもあります。
2. 機械向けのAPIドキュメント
機械が処理しやすい形式で書かれたAPIドキュメントは、APIの統合や検証を自動化するために利用されます。主なフォーマットとして、以下のものがあります。
- OpenAPI（Swagger） - JSONまたはYAML形式で記述
- RAML - RESTful APIの設計に特化したフォーマット
- GraphQL Schema - GraphQL APIの構造を定義
- WSDL - XMLベースのSOAP API用のフォーマット
3. APIリコンの際のドキュメント活用
APIが外部開発者向けに公開されている場合、最初にドキュメントを確認することが重要です。以下の手順で情報を収集しましょう。
- 公式サイトをチェック
APIの公式ドキュメントがあるか確認する（例:https://developer.example.com/docs）。 - Swagger UIやPostmanでAPI仕様を確認
インタラクティブなドキュメントを利用してエンドポイントを探索する。 - エラーメッセージやリクエストログを分析
ドキュメントに記載されていない隠れたパラメータやエンドポイントを見つける手がかりになる。 - GitHubやStack Overflowを検索
APIの非公式な情報や、開発者の議論から追加の情報を得る。
APIドキュメントは攻撃対象領域（アタックサーフェス）を特定するための貴重な情報源です。リコン（情報収集）の際には必ず確認しましょう。
Best regards, (^^ゞ
