Zurück zur Startseite

GoatixAnalytics API Dokumentation

RESTful API für Server Management und Metriken

1. Getting Started

Die GoatixAnalytics API ermöglicht es dir, deine Server zu verwalten und Leistungsmetriken zu speichern und abzurufen.

Voraussetzungen

  • Du benötigst einen API Token für deinen Server
  • Der API Token wird beim Erstellen eines Servers generiert
  • Der Token ist einzigartig und sollte geheim gehalten werden
  • Alle API Anfragen müssen über HTTPS erfolgen

Deinen API Token findest du:

  1. Melde dich bei GoatixAnalytics an
  2. Gehe zu /dashboard/servers
  3. Wähle deinen Server und klicke auf "Bearbeiten"
  4. Du siehst dort deinen API Token (eine 40 Zeichen lange Zeichenkette)

2. Authentifizierung

Alle API Endpoints (außer Health Check) erfordern Authentifizierung mit deinem API Token.

Authorization: Bearer YOUR_API_TOKEN

Beispiel mit curl:

curl -X GET https://www.goatixanalytics.eu/api/v1/servers/me \
  -H "Authorization: Bearer your_api_token_here"

⚠️ Sicherheitshinweis

  • Gib deinen API Token niemals an Dritte weiter
  • Lagere ihn nicht im Quellcode (nutze Umgebungsvariablen)
  • Regeneriere deinen Token regelmäßig
  • Wenn du glaubst, dass der Token kompromittiert wurde, regeneriere ihn sofort

3. Rate Limiting

Die API hat Rate Limiting, um Missbrauch zu verhindern:

Limit: 10 Anfragen pro Minute pro API Token

(Maximal 1 Anfrage alle 10 Sekunden)

Wenn du dieses Limit überschreitest, erhältst du einen 429 Too Many Requests Response.

Empfehlung: Speichere Metriken alle 10 Sekunden (oder seltener).

4. API Endpoints

GET /api/v1/servers/me

Rufe Informationen über deinen Server ab

Beispiel:

curl -X GET https://www.goatixanalytics.eu/api/v1/servers/me \
  -H "Authorization: Bearer your_api_token"

Erfolgreiche Antwort (200 OK):

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Mein Minecraft Server",
    "description": "Ein schöner Server",
    "active": true,
    "is_public": true,
    "is_stats_public": true,
    "created_at": "2025-11-28T10:30:00Z",
    "updated_at": "2025-11-28T15:45:00Z"
  }
}

PUT /api/v1/servers/me

Aktualisiere deinen Server

Editierbare Felder:

  • name (string, max 200)
  • description (string, max 5000, nullable)
  • is_public (boolean)
  • is_stats_public (boolean)
  • active (boolean)

Beispiel:

curl -X PUT https://www.goatixanalytics.eu/api/v1/servers/me \
  -H "Authorization: Bearer your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aktualisierter Name",
    "is_public": true
  }'

POST /api/v1/metrics

Speichere Metriken deines Servers

Verfügbare Felder (alle optional außer timestamp):

Basis Performance:

  • timestamp (required, date)
  • cpu_usage (numeric: 0-100, %)
  • memory_usage_percent (numeric: 0-100, %)
  • tps (numeric: 0-20)
  • mspt (numeric, milliseconds per tick)
  • tick_time (numeric, milliseconds)

Memory & Heap:

  • ram_used, ram_total (integer, bytes)
  • java_heap_used, java_heap_max (integer, bytes)

Storage & Disk:

  • disk_used, disk_total (integer, bytes)
  • disk_read_speed, disk_write_speed (numeric, MB/s)
  • world_size (integer, bytes)

Spieler & Minecraft:

  • player_count, max_players (integer)
  • loaded_chunks, entity_count (integer)
  • mod_count, plugin_count (integer)

Netzwerk & Verbindung:

  • network_in, network_out (integer, bytes)
  • ping_average (integer, milliseconds)
  • bandwidth_usage (numeric, Mbps)
  • packet_loss (numeric: 0-100, %)

System:

  • uptime (integer, seconds)
  • thread_count (integer)
  • additional_data (nullable, JSON object für custom Felder)

Beispiel (minimal):

curl -X POST https://www.goatixanalytics.eu/api/v1/metrics \
  -H "Authorization: Bearer your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "2025-11-28T16:30:00Z",
    "cpu_usage": 45.5,
    "mspt": 25.5,
    "memory_usage_percent": 72.5,
    "player_count": 12,
    "max_players": 20,
    "tps": 19.8
  }'

Erfolgreiche Antwort (201 Created):

{
  "success": true,
  "message": "Metric recorded successfully",
  "data": {
    "id": 123,
    "server_id": 1,
    "timestamp": "2025-11-28T16:30:00Z",
    "cpu_usage": 45.5,
    ...
  }
}

GET /api/v1/metrics

Rufe deine Metriken ab (mit optionalen Filtern)

Query Parameter:

  • from (optional, date) - Start Datum
  • to (optional, date) - End Datum

Beispiel:

curl -X GET "https://www.goatixanalytics.eu/api/v1/metrics?from=2025-11-01&to=2025-11-28" \
  -H "Authorization: Bearer your_api_token"

5. Fehlerbehandlung

Die API gibt konsistente Fehlermeldungen zurück:

401 Unauthorized - Fehlende oder ungültiger Token

{
  "success": false,
  "message": "Unauthorized: Invalid API token"
}

422 Unprocessable Entity - Validierungsfehler

{
  "success": false,
  "message": "The name field is required.",
  "errors": {
    "name": ["The name field is required."]
  }
}

429 Too Many Requests - Rate Limit überschritten

{
  "message": "Too Many Requests"
}

6. Best Practices

Metriken alle 10 Sekunden speichern

Die API erlaubt 10 Anfragen pro Minute. Am besten ist es, Metriken alle 10 Sekunden (oder seltener) zu senden.

Token in Umgebungsvariablen speichern

Lege deinen API Token in einer .env Datei oder einer Umgebungsvariable ab, nicht im Quellcode.

Fehler behandeln

Überprüfe immer das success Flag und behandle Fehler graceful (z.B. retry bei Timeout).

Timestamps präzise setzen

Nutze exakte ISO 8601 Timestamps (z.B. 2025-11-28T16:30:00Z). Dies ermöglicht bessere Analysen.