📋 目次

📖 概要

Best Auction APIは、Minecraftサーバー間でオークション情報を共有するためのRESTful APIです。

ベースURL

https://best-auction-cloud.masafumi-t.workers.dev

データ形式

すべてのAPIエンドポイントはJSON形式でデータを送受信します。

🔐 認証

すべてのAPIリクエストには Bearer トークンによる認証が必要です。

認証ヘッダー

Authorization: Bearer YOUR_API_TOKEN

トークンの取得

APIトークンはダッシュボードから生成できます。

POST /api/auth/validate
APIトークンの有効性を検証します。
{ "success": true, "data": { "valid": true, "token": { "server_id": "my-server", "permissions": "read,write", "username": "user123" } } }

🏷️ オークション関連

GET /api/auctions/{serverId}
指定されたサーバーのオークション一覧を取得します。

パラメータ

パラメータ タイプ 必須 説明
serverId string 必須 サーバーID
active_only boolean 任意 アクティブなオークションのみ
limit number 任意 取得件数（最大100）
offset number 任意 オフセット

レスポンス例

{ "success": true, "data": [ { "auction_id": 123, "server_id": "my-server", "seller_name": "PlayerName", "item_name": "Diamond Sword", "item_type": "DIAMOND_SWORD", "quantity": 1, "current_price": 1000, "buyout_price": 1500, "category": "WEAPON", "created_at": "2025-06-19T12:00:00Z", "expires_at": "2025-06-26T12:00:00Z", "is_active": true, "is_sold": false } ] }
GET /api/auctions/{serverId}/{auctionId}
特定のオークションの詳細情報を取得します。

パラメータ

パラメータ タイプ 必須 説明
serverId string 必須 サーバーID
auctionId number 必須 オークションID

🖥️ サーバー関連

GET /api/servers
利用可能なサーバーの一覧を取得します。

レスポンス例

{ "success": true, "data": [ { "server_id": "main-server", "auction_count": 150, "last_activity": "2025-06-19T14:30:00Z" }, { "server_id": "creative-server", "auction_count": 45, "last_activity": "2025-06-19T14:25:00Z" } ] }
GET /api/servers/{serverId}/stats
サーバーの統計情報を取得します。

📊 イベント関連

GET /api/events/{serverId}
サーバーのイベント履歴を取得します。

イベントタイプ

  • ITEM_LISTED - アイテム出品
  • BID_PLACED - 入札
  • BID_CANCELLED - 入札キャンセル
  • AUCTION_CANCELLED - オークションキャンセル
  • ITEM_SOLD - アイテム販売完了
POST /api/events
新しいイベントを送信します（プラグイン用）。

リクエスト例

{ "event_type": "ITEM_LISTED", "server_id": "my-server", "timestamp": "2025-06-19T14:30:00", "auction_id": 123, "data": { "seller_uuid": "123e4567-e89b-12d3-a456-426614174000", "seller_name": "PlayerName", "item_name": "Diamond Sword", "item_type": "DIAMOND_SWORD", "quantity": 1, "start_price": 1000 } }

📋 レスポンス形式

成功レスポンス

{ "success": true, "data": {...}, "message": "Success" }

エラーレスポンス

{ "success": false, "error": "Error message", "message": "Additional details" }

⚠️ エラーハンドリング

ステータスコード 説明 対処法
400 Bad Request - リクエストが無効 リクエストパラメータを確認
401 Unauthorized - 認証エラー APIトークンを確認
403 Forbidden - 権限不足 トークンの権限を確認
404 Not Found - リソースが見つからない URLとパラメータを確認
500 Internal Server Error - サーバーエラー 時間をおいて再試行

レート制限

APIには1分間に100リクエストの制限があります。制限を超えた場合は429ステータスコードが返されます。