hubmc-datagw/API_EXAMPLES.md

# API Examples

Примеры использования API для HubGW.

## Аутентификация

Все запросы (кроме `/health`) требуют заголовок `X-API-Key` с правильным API ключом.

```bash
curl -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     http://localhost:8080/api/v1/health/
```

## Homes

### Создать/обновить дом
```bash
curl -X PUT \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "player_uuid": "123e4567-e89b-12d3-a456-426614174000",
       "name": "my_home",
       "world": "world",
       "x": 100.5,
       "y": 64.0,
       "z": 200.3,
       "yaw": 90.0,
       "pitch": 0.0,
       "is_public": 0
     }' \
     http://localhost:8080/api/v1/homes/
```

### Получить дом
```bash
curl -X POST \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "player_uuid": "123e4567-e89b-12d3-a456-426614174000",
       "name": "my_home"
     }' \
     http://localhost:8080/api/v1/homes/get
```

### Список домов игрока
```bash
curl -H "X-API-Key: your-secret-api-key" \
     http://localhost:8080/api/v1/homes/123e4567-e89b-12d3-a456-426614174000
```

## Kits

### Запросить набор
```bash
curl -X POST \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "player_uuid": "123e4567-e89b-12d3-a456-426614174000",
       "kit_name": "starter"
     }' \
     http://localhost:8080/api/v1/kits/claim
```

## Cooldowns

### Проверить кулдаун
```bash
curl -X POST \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "player_uuid": "123e4567-e89b-12d3-a456-426614174000",
       "key": "kit_starter"
     }' \
     http://localhost:8080/api/v1/cooldowns/check
```

### Установить кулдаун
```bash
curl -X PUT \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "key": "kit_starter"
     }' \
     "http://localhost:8080/api/v1/cooldowns/touch?seconds=3600&player_uuid=123e4567-e89b-12d3-a456-426614174000"
```

## Warps

### Создать варп
```bash
curl -X POST \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "spawn",
       "world": "world",
       "x": 0.0,
       "y": 64.0,
       "z": 0.0,
       "yaw": 0.0,
       "pitch": 0.0,
       "is_public": 1,
       "description": "Main spawn point"
     }' \
     http://localhost:8080/api/v1/warps/
```

### Обновить варп
```bash
curl -X PATCH \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "spawn",
       "world": "world_nether",
       "description": "Updated spawn point"
     }' \
     http://localhost:8080/api/v1/warps/
```

### Удалить варп
```bash
curl -X DELETE \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "spawn"
     }' \
     http://localhost:8080/api/v1/warps/
```

### Получить варп
```bash
curl -X POST \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "spawn"
     }' \
     http://localhost:8080/api/v1/warps/get
```

### Список варпов
```bash
curl -X POST \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "page": 1,
       "size": 20,
       "world": "world",
       "is_public": 1
     }' \
     http://localhost:8080/api/v1/warps/list
```

## Whitelist

### Добавить игрока в вайтлист
```bash
curl -X POST \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "player_name": "PlayerName",
       "player_uuid": "123e4567-e89b-12d3-a456-426614174000",
       "added_by": "admin",
       "reason": "VIP player"
     }' \
     http://localhost:8080/api/v1/whitelist/add
```

### Удалить игрока из вайтлиста
```bash
curl -X POST \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "player_name": "PlayerName"
     }' \
     http://localhost:8080/api/v1/whitelist/remove
```

### Проверить вайтлист
```bash
curl -X POST \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "player_name": "PlayerName"
     }' \
     http://localhost:8080/api/v1/whitelist/check
```

### Список вайтлиста
```bash
curl -H "X-API-Key: your-secret-api-key" \
     http://localhost:8080/api/v1/whitelist/
```

## Punishments

### Создать наказание
```bash
curl -X POST \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "player_uuid": "123e4567-e89b-12d3-a456-426614174000",
       "player_name": "PlayerName",
       "punishment_type": "ban",
       "reason": "Cheating",
       "staff_uuid": "987fcdeb-51a2-43d1-b456-426614174000",
       "staff_name": "Admin",
       "expires_at": "2024-12-31T23:59:59Z"
     }' \
     http://localhost:8080/api/v1/punishments/
```

### Отменить наказание
```bash
curl -X POST \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "punishment_id": "456e7890-e89b-12d3-a456-426614174000",
       "revoked_by": "987fcdeb-51a2-43d1-b456-426614174000",
       "revoked_reason": "Appeal accepted"
     }' \
     http://localhost:8080/api/v1/punishments/revoke
```

### Запрос наказаний
```bash
curl -X POST \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "player_uuid": "123e4567-e89b-12d3-a456-426614174000",
       "punishment_type": "ban",
       "is_active": true,
       "page": 1,
       "size": 20
     }' \
     http://localhost:8080/api/v1/punishments/query
```

### Статус бана
```bash
curl -H "X-API-Key: your-secret-api-key" \
     http://localhost:8080/api/v1/punishments/ban/123e4567-e89b-12d3-a456-426614174000
```

### Статус мута
```bash
curl -H "X-API-Key: your-secret-api-key" \
     http://localhost:8080/api/v1/punishments/mute/123e4567-e89b-12d3-a456-426614174000
```

## Audit

### Логирование команды
```bash
curl -X POST \
     -H "X-API-Key: your-secret-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "player_uuid": "123e4567-e89b-12d3-a456-426614174000",
       "player_name": "PlayerName",
       "command": "tp",
       "arguments": ["player2"],
       "server": "hub",
       "timestamp": "2024-01-01T12:00:00Z"
     }' \
     http://localhost:8080/api/v1/audit/commands
```