API hinzugefügt
277
API.md
Normal file
277
API.md
Normal file
@@ -0,0 +1,277 @@
|
||||
Willkommen im Wiki.# HTTP API Dokumentation
|
||||
|
||||
StatusAPI stellt einen integrierten HTTP-Server auf **Port 9191** bereit, über den externe Anwendungen mit dem Plugin kommunizieren können.
|
||||
|
||||
## Basis-URL
|
||||
|
||||
```
|
||||
http://dein-server:9191
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Endpunkte
|
||||
|
||||
### GET /status
|
||||
|
||||
Gibt den aktuellen Serverstatus zurück.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"online": true,
|
||||
"players": 42,
|
||||
"maxPlayers": 100,
|
||||
"servers": [
|
||||
{
|
||||
"name": "lobby",
|
||||
"players": 15
|
||||
},
|
||||
{
|
||||
"name": "survival",
|
||||
"players": 27
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### POST /broadcast
|
||||
|
||||
Sendet eine Broadcast-Nachricht an alle Online-Spieler.
|
||||
|
||||
**Request Headers:**
|
||||
```
|
||||
Content-Type: application/json
|
||||
X-API-Key: <dein-api-key> (optional, wenn in config gesetzt)
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"sourceName": "System",
|
||||
"message": "Server startet in 5 Minuten neu!",
|
||||
"type": "global",
|
||||
"prefix": "[Info]",
|
||||
"prefixColor": "&e",
|
||||
"bracketColor": "&8",
|
||||
"messageColor": "&f"
|
||||
}
|
||||
```
|
||||
|
||||
**Parameter:**
|
||||
|
||||
| Parameter | Typ | Erforderlich | Beschreibung |
|
||||
|-----------|-----|--------------|--------------|
|
||||
| `sourceName` | String | Nein | Name der Quelle (Standard: "System") |
|
||||
| `message` | String | Ja | Die Nachricht |
|
||||
| `type` | String | Nein | Broadcast-Typ (Standard: "global") |
|
||||
| `prefix` | String | Nein | Prefix vor der Nachricht |
|
||||
| `prefixColor` | String | Nein | Farbcode für den Prefix |
|
||||
| `bracketColor` | String | Nein | Farbcode für die Klammern `[]` |
|
||||
| `messageColor` | String | Nein | Farbcode für die Nachricht |
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"recipients": 42
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### POST /broadcast/schedule
|
||||
|
||||
Plant einen Broadcast für einen späteren Zeitpunkt.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"sourceName": "System",
|
||||
"message": "Tägliche Wartung beginnt!",
|
||||
"timestamp": 1700000000000,
|
||||
"type": "global",
|
||||
"prefix": "[Wartung]",
|
||||
"prefixColor": "&c",
|
||||
"messageColor": "&f",
|
||||
"recur": "daily",
|
||||
"clientScheduleId": "daily-maintenance"
|
||||
}
|
||||
```
|
||||
|
||||
**Parameter:**
|
||||
|
||||
| Parameter | Typ | Erforderlich | Beschreibung |
|
||||
|-----------|-----|--------------|--------------|
|
||||
| `timestamp` | Long | Ja | Unix-Timestamp in Millisekunden |
|
||||
| `recur` | String | Nein | Wiederholung: `none`, `hourly`, `daily`, `weekly` |
|
||||
| `clientScheduleId` | String | Nein | Eindeutige ID für den geplanten Broadcast |
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"scheduleId": "daily-maintenance",
|
||||
"scheduledFor": "2024-01-15 12:00:00 UTC"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### DELETE /broadcast/schedule/{id}
|
||||
|
||||
Bricht einen geplanten Broadcast ab.
|
||||
|
||||
**Request:**
|
||||
```
|
||||
DELETE /broadcast/schedule/daily-maintenance
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"cancelled": "daily-maintenance"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Farbcodes
|
||||
|
||||
StatusAPI unterstützt Minecraft-Farbcodes mit dem `&` Prefix:
|
||||
|
||||
| Code | Farbe |
|
||||
|------|-------|
|
||||
| `&0` | Schwarz |
|
||||
| `&1` | Dunkelblau |
|
||||
| `&2` | Dunkelgrün |
|
||||
| `&3` | Dunkelaqua |
|
||||
| `&4` | Dunkelrot |
|
||||
| `&5` | Lila |
|
||||
| `&6` | Gold |
|
||||
| `&7` | Grau |
|
||||
| `&8` | Dunkelgrau |
|
||||
| `&9` | Blau |
|
||||
| `&a` | Grün |
|
||||
| `&b` | Aqua |
|
||||
| `&c` | Rot |
|
||||
| `&d` | Pink |
|
||||
| `&e` | Gelb |
|
||||
| `&f` | Weiß |
|
||||
| `&l` | Fett |
|
||||
| `&n` | Unterstrichen |
|
||||
| `&o` | Kursiv |
|
||||
| `&m` | Durchgestrichen |
|
||||
| `&r` | Reset |
|
||||
|
||||
---
|
||||
|
||||
## API-Authentifizierung
|
||||
|
||||
Optional kann ein API-Key in der `verify.properties` konfiguriert werden:
|
||||
|
||||
```properties
|
||||
broadcast.api_key=dein-geheimer-api-key
|
||||
```
|
||||
|
||||
Wenn gesetzt, muss der Key im Header mitgesendet werden:
|
||||
|
||||
```
|
||||
X-API-Key: dein-geheimer-api-key
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Beispiele
|
||||
|
||||
### cURL - Sofortiger Broadcast
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:9191/broadcast \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"message": "Willkommen auf dem Server!",
|
||||
"prefix": "[Info]",
|
||||
"prefixColor": "&a"
|
||||
}'
|
||||
```
|
||||
|
||||
### cURL - Geplanter Broadcast
|
||||
|
||||
```bash
|
||||
# Timestamp für morgen 12:00 Uhr
|
||||
TIMESTAMP=$(($(date -d "tomorrow 12:00" +%s) * 1000))
|
||||
|
||||
curl -X POST http://localhost:9191/broadcast/schedule \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{
|
||||
\"message\": \"Server-Restart in 5 Minuten!\",
|
||||
\"timestamp\": $TIMESTAMP,
|
||||
\"recur\": \"daily\",
|
||||
\"clientScheduleId\": \"daily-restart-warning\"
|
||||
}"
|
||||
```
|
||||
|
||||
### Python - Broadcast senden
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
url = "http://localhost:9191/broadcast"
|
||||
data = {
|
||||
"message": "Python sagt Hallo!",
|
||||
"prefix": "[Bot]",
|
||||
"prefixColor": "&b",
|
||||
"messageColor": "&f"
|
||||
}
|
||||
|
||||
response = requests.post(url, json=data)
|
||||
print(response.json())
|
||||
```
|
||||
|
||||
### JavaScript/Node.js - Broadcast senden
|
||||
|
||||
```javascript
|
||||
const fetch = require('node-fetch');
|
||||
|
||||
const url = 'http://localhost:9191/broadcast';
|
||||
const data = {
|
||||
message: 'Node.js sagt Hallo!',
|
||||
prefix: '[Bot]',
|
||||
prefixColor: '&e'
|
||||
};
|
||||
|
||||
fetch(url, {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify(data)
|
||||
})
|
||||
.then(res => res.json())
|
||||
.then(json => console.log(json));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Fehlerbehandlung
|
||||
|
||||
### HTTP Status Codes
|
||||
|
||||
| Code | Bedeutung |
|
||||
|------|-----------|
|
||||
| `200` | Erfolgreich |
|
||||
| `400` | Ungültige Anfrage |
|
||||
| `401` | API-Key ungültig oder fehlt |
|
||||
| `404` | Endpunkt nicht gefunden |
|
||||
| `500` | Interner Serverfehler |
|
||||
|
||||
### Fehler-Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Modul ist deaktiviert"
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user