API定義を評価する際に何を確認すべきですか？

API定義：それが何か

API定義とは、クライアントがAPIをどのように呼び出すべきか、そしてAPIがどのように応答するかを説明する、ドキュメント化された契約です。通常、エンドポイントのルート、リクエスト／レスポンスの形式（たとえばJSONフィールド）、データ型、必須と任意のパラメータ、認証と権限、レート制限、エラー形式、さらに明示されたタイミングや順序に関する期待などが含まれます。

自動取引の文脈では、API定義が重要なのは、下流のあらゆるステップ――データ取り込み、シグナルロジック、執行判断、レポーティング――が、APIが保証するものと、単に「提供しようとする」だけのものの違いに依存するからです。評価の主要な目的は、どの部分が安定した仕組みで、どの部分が市場条件、システム負荷、提供者のポリシーによって変わり得るのかを理解することです。

API定義の確認方法（客観的チェックリスト）

1. 契約の網羅性（afvinkpunten）

• エンドポイントとメソッドが明示的に列挙されている。
• リクエストおよびレスポンスのスキーマが定義されており、フィールドの意味やデータ型が含まれている。
• 通常のレスポンスと、各ドキュメント化されたエラータイプについて例が存在する。
• 認証・認可の要件が明記されている（たとえば、クレデンシャルの渡し方や、許可されるアクセス範囲）。

2. 挙動の詳細（「仕組み」の部分）

• APIが呼び出し間の順序や一貫性を定義しているか確認する（たとえば、「latest」がタイムスタンプに結び付いているかどうか）。
• タイムスタンプの表現方法を確認する（形式、タイムゾーン、そしてイベント時刻なのか処理時刻なのか）。
• ページネーション、フィルタリング、制限の仕組みを検証する。最大ページサイズやデフォルト値も含める。

3. 変動する条件 vs 安定した仕組み

• 安定要素（スキーマ、パラメータ規則、ドキュメント化されたエラーコード）と、変動要素（レイテンシ、データの欠落、マーケットの動き、負荷によるスロットリング）を分ける。
• 「リアルタイム」や「ストリーミング」に関する記述は、固定の約束としてではなく、テストやサンプルレスポンスで検証すべき挙動上の主張として扱う。

4. 根拠とドキュメントによる証明 契約を検証できる実装上の成果物を探す：

• サンプルのペイロードやエラー応答を含むドキュメント。
• 変更がどのように導入され、旧バージョンがどれくらいの期間サポートされるかを説明するバージョニングポリシー。
• サンドボックス環境、モックエンドポイント、または記録されたサンプル呼び出しといったテストリソース。

5. 明確な制限の記述（rode vlaggen） ドキュメントが沈黙している、または曖昧な箇所を特定する：

• 重要なフィールドの定義が欠けている。
• エラーの意味論が不明確（たとえば、エラーがリトライ可能かどうか）。
• バックプレッシャー、レート制限の挙動、部分的な障害時に何が起きるのかの説明がない。

根拠または例：何をもって「検証」とするか

根拠に基づく評価の実践例は、次のようなスクリプト化した呼び出しを実行してカバーすることです：

• 「ハッピーパス」のリクエストを行い、レスポンスのフィールドがドキュメント化されたスキーマと一致することを確認する。
• 少なくとも1つの境界条件。たとえば、ドキュメント化されたエラーを引き起こすはずの無効なパラメータ。
• レイテンシ／タイミングの確認。往復時間を測定し、提示されているタイミング期待値と比較する。

前提の例（明示する）：自分のシステムクロックからレスポンス時間を測定する場合、そのクロックが合理的に同期されていると仮定します。この仮定がないと、タイミング比較は誤解を招く可能性があります。

考慮すべき制限と失敗パターン

少なくとも、重要な失敗パターンを1つ以上評価してください：

• データ欠落：APIは不完全な履歴を返す、イベントが欠ける、更新が遅れる可能性がある。
• レイテンシと順序の問題：タイムスタンプが存在しても、呼び出しの順序がイベントの順序と一致しない場合がある。
• レート制限またはスロットリング：過剰なリクエストは遅延や構造化されたエラーにつながる。
• スキーマのドリフト：APIバージョンがフィールド、型、必須パラメータを変更する可能性がある。
• 認証／権限の失敗：トークンが期限切れになる、または環境によってアクセススコープが異なる可能性がある。

過去の関係は将来の結果を保証しません。サンプルレスポンスが一貫して見えても、提供者がサービスを更新したり、システム負荷や市場のボラティリティが変化したりすると、将来の挙動は変わり得ます。結果はコスト、執行方法、管轄（jurisdiction）によっても変わるため、API定義をパフォーマンス保証ではなく「契約の説明」として扱ってください。

検証基準と次に確認すべき質問

統合前に、明確な「klaarcriterium（done-criteria）」を使ってください：

• 必須パラメータと、返されるすべてのフィールドを、ドキュメント化された意味に対応付けできる。
• テスト環境で、ドキュメント化された成功およびエラー応答を再現できる。
• タイミング、リトライ、データの完全性について、ドキュメント化された前提がある。
• レート制限、未知フィールド、バージョン変更への対応計画がある。

評価中に次の質問をする：

• タイムスタンプと順序に関する、APIのドキュメント化された一貫性モデルは具体的に何ですか？ - どのエラーがリトライ可能で、どのようなバックオフのガイダンスが提供されていますか？