APIドキュメント
インタラクティブな Swagger ドキュメントを使用して完全な Balla Stats API を探索します。エンドポイントをテストし、スキーマを表示し、ブラウザーで直接認証します。
前提条件
API ドキュメントを参照する前に、以下が必要です。
- Balla Stats アカウント
- REST API の基本的な理解
インタラクティブな Swagger ドキュメントを使用して完全な Balla Stats API を探索します。エンドポイントをテストし、スキーマを表示し、ブラウザーで直接認証します。
エンドポイントを試す
API呼び出しをライブで実行する
スキーマの表示
TypeScript と互換性のある型
認証
JWT と API キーのサポート
- API ドキュメントにアクセスする
- Swagger で認証する
- エンドポイントを探索する
- API呼び出しを試してみる
- 応答スキーマを理解する
- 一般的な API パターン
ブラウザで /api-docs に移動するか、サイドバーで API Docs をクリックします。 Swagger UI は、使用可能なすべてのエンドポイントを含む完全な API リファレンスを読み込みます。
ページの上部にある 「承認」 ボタンをクリックします。 Bearer トークン (ログインからの JWT または API キー) を入力します。これにより、Swagger UI を通じて行われる後続のすべてのリクエストが認証されます。
エンドポイントはカテゴリ別に整理されており、簡単にナビゲーションできます。セクションを展開すると、利用可能な操作が表示されます。
任意のエンドポイントで 「試してみる」 をクリックして対話型にします。必要なパラメータを入力し、「実行」 をクリックします。応答本文、ヘッダー、ステータス コードが以下に表示されます。
エンドポイントの下にある Schema セクションを展開すると、完全な応答構造が表示されます。これらの型は、@balla-stats/types パッケージの TypeScript 定義と互換性があるため、タイプセーフな統合を簡単に構築できます。
スキーマの機能
- フィールド タイプ: 文字列、数値、ブール値、配列、正確な型定義を持つオブジェクト
- 必須フィールド: オプションのプロパティと必須のプロパティを区別するために明確にマークされています
- Enums: ステータス フィールド、ロール、タイプに許可される正確な値
- ネストされたオブジェクト: 展開して完全な関係構造を表示可能
Balla Stats API は、すべてのエンドポイントにわたって一貫したパターンに従います。
ページネーション
page および limit クエリ パラメーターを使用します。応答には、合計数と現在のページのメタデータが含まれます。
フィルタリング
status、teamId、seasonId、日付範囲などのクエリ パラメーターを使用して結果をフィルターします。
エラー応答
message および statusCode フィールドの一貫した形式。検証エラーにはフィールドレベルの詳細が含まれます。
日付形式
すべての日付は ISO 8601 形式を使用します (例: 2026-02-16T10:30:00.000Z)。タイムスタンプは常に UTC です。
コーディング前のテスト
統合コードを作成する前のテストには Swagger を使用します。エンドポイントが期待したデータを返すことを確認します。
すべてのフィールドをチェックする
使用可能なすべてのフィールドの応答スキーマを確認してください。応答には、予想よりも多くのデータが含まれることがよくあります。
レート制限が適用されます
レート制限は Swagger リクエストにも適用されます。広範囲にテストする場合は、API キーを使用して制限を高めます。
Swagger の 401 エラー
- 「承認」ボタンをクリックして、最初にトークンを入力します
- 余分なスペースを含まない完全なトークンを必ず含めてください
- JWT トークンの有効期限が切れます - セッションがタイムアウトした場合は、再度ログインしてください
空の応答
- クエリパラメータが正しいことを確認してください（有効なグループIDなど）
- 要求されたリソースにアクセスできることを確認してください
- リソースが存在することを確認してください - 最初にすべての項目をリストしてみてください