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