League API Engineering
ちょうど1つのプライマリモードを選択します。混合リクエストの場合は、先に進む前に支配的なモードとセカンダリの成果物を明示します。
| モード | 使用目的 | 必須成果物 |
|---|---|---|
implement | データ連携を追加または変更 | ソース決定 → アダプターコントラクト → サニタイズ済みフィクスチャ/テスト → 実装計画またはコード → ゲート |
audit | 既存の連携を評価 | インベントリ → エビデンスラベル → リスクマトリックス → 優先順位付けされたソース固有の修正 |
debug | 動作不良または誤解を招く連携のデバッグ | 再現手順 → 障害クラス → トランスポート/スキーマ/キャッシュ/フォールバックの調査 → 修正の証明 |
research | ソースの選定または最新情報の確認 | 日付付きエビデンスマップ → ソース評価 → 判断 |
policy | データ利用または製品動作が許可されているかの判定 | 製品/データレビュー → ポリシーゲート → 許可、制約付き、または禁止の判断 |
譲れないゲート条件
失敗したゲートを回避するのではなく、設計を拒否します。
- シークレットとプライバシー: Riotキー、LCU資格情報、ベアラートークン、クッキー、PII、実際のプレイヤーの履歴を埋め込み、永続化、またはログ出力してはなりません。
- ローカルクライアントの安全性: インジェクション、フック、プロセスメモリアクセス、メモリスキャン、アンチチートバイパス、隠れ状態の抽出、専用フルスクリーン制御の主張を禁止します。ループバック証明書の緩和は、
127.0.0.1またはlocalhostに明示的にバインドされたクライアントに限定され、リモートHTTPSに再利用することは決してできません。 - 権限と利用規約: 文書化されていないエンドポイントやプロバイダーを公式サポート済みとして表現してはなりません。使用前に、適用される利用規約、帰属表示、再配布、認証、レート制限の条件を確認します。
- フォールバックの正確性: フォールバックは、母集団、範囲、鮮度、パッチ、ロケール、キュー、出所のセマンティクスを保持しなければなりません。実質的に異なるデータは、無言の代替ではなく、別個の結果として扱います。
- 非サポートリクエスト: MMR/ELO推定値を発明したり、隠れ状態を推測したり、利用不可能なプレイヤー情報を公開したりしてはなりません。その場合は、制約とともに
policy_blockedまたはunsupported_contextを返します。
ソース決定ワークフロー
- 要求されたデータを分類します: ローカルセッション、アクティブマッチ、静的/バージョン管理データ、リモートアカウント/マッチ/ランクデータ、集計トレンドデータ、または非サポート/隠れ状態。
source-decision-tree.mdから開始します。権限、アクセス可能性、ルーティング、鮮度、安定性、パッチカバレッジ、レイテンシ、利用規約、プライバシー、帰属表示、レート制限、障害動作に基づいて候補を選択します。- スコアリングの前に厳格なゲートを適用します。埋め込み型本番キー、安全でないローカルアクセス、禁止データ、未レビューの再配布、互換性のないフォールバックが必要なソースは拒否します。
- 各重要な主張に対してエビデンスクラスを記録します:
verified-current: 日付付きの信頼できるソースまたは現在の再現可能な観察によって直接サポートされています。observed-undocumented: 再現された動作ですが、信頼できるソースによって保証されていません。historical: かつて文書化または観察されたものであり、現在も有効であると仮定するのは安全ではありません。inference: 検証が必要な推論された結論であり、本番環境に使用する前の確認が必要です。
adapter-contract.mdを使用してアダプターコントラクトを記述または更新し、キャッシュ/フォールバック、テスト、カナリア制御を採用します。
障害語彙
1つの主要なエラークラスを使用し、生のサニタイズ済み診断情報は別途保持します: offline、unauthorized、rate_limited、not_found、no_data、unsupported_context、transport、http_status、parse、schema_drift、policy_blocked のいずれか。
unauthorized、policy_blocked、parse、schema_drift に対しては決して盲目的にリトライしてはなりません。 caching-and-fallbacks.md を参照してください。
監査出力契約
監査は日付付きの成果物を生成し、以下を含みます。
- スコープ、データクラス、アダプターのインベントリ。
- 権限、安定性、エビデンスクラス、利用規約レビュー日付を含むソース/エンドポイントマップ。
- 資格情報、プライバシー、ローカルアクセス、ルーティング、バージョニング、帰属表示に関する調査結果。
- キャッシュ、データなし、リトライ、ドリフト、フォールバック互換性に関する調査結果。
- リスクマトリックス: 深刻度、可能性、影響を受ける動作、エビデンス、具体的な是正措置。
- 優先順位付けされた修正、ブロックされた項目、検証基準。
仮定を検証済みとラベル付けしてはいけません。たまたま1回動作したという理由だけでソースを安全と判断してはいけません。
段階的開示
- 公式およびローカルソースの選択:
riot-web-apis.md、lcu.md、live-client-data.md、data-dragon.md、communitydragon.md。 - 外部ソースと製品ポリシー:
third-party-providers.md、policy-and-product-gates.md。 - エンジニアリング制御:
adapter-contract.md、caching-and-fallbacks.md、testing-and-canaries.md。 - オプションの限定された例:
case-study-lolcompanion.md。
バリデーターが存在する場合は、公開前にパッケージルートから python scripts/validate.py . を実行します。