RagnaAPI – Technische Dokumentation

Einführung

Die RagnaAPI ist das Herzstück der Ragnarök-Infrastruktur. Sie verwaltet alle Mitgliederdaten, Achievement-Systeme, Bildergalerien und Statistiken. Die API ist RESTful aufgebaut und liefert JSON-Responses.

Base URL

https://www.xn--ragnark-f1a.eu/neu/doc/api_backend/

Request Format

Alle Requests werden über HTTP(S) gestellt. POST-Requests erwarten application/json oder application/x-www-form-urlencoded Content-Types.

Authentifizierung

Die meisten öffentlichen Endpoints benötigen keine Authentifizierung. Administrative Endpoints (z.B. Achievement-Vergabe) erfordern eine Session-basierte Authentifizierung über das Admin-Panel.

Session Auth (Admin)

// Login über Admin-Panel erforderlich
// Session-Cookie wird automatisch gesetzt
Cookie: PHPSESSID=<session_id>

Tech Stack

Die Infrastruktur basiert auf bewährten Technologien mit Fokus auf Performance und Wartbarkeit.

PHP 8.x

Backend-Logik mit PDO für sichere Datenbankzugriffe

MySQL 8.0

Relationale Datenbank für Mitglieder, Achievements, Logs

REST/JSON

Standardisierte API-Kommunikation

PDO Prepared

SQL Injection Prevention durch Prepared Statements

Members Endpoint

Verwaltet alle Mitgliederdaten der Kriegsnation.

GET /api_members.php

Gibt alle aktiven Mitglieder mit Rang, Level und Achievements zurück.

Response

JSON Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Mausi",
      "level": 5,
      "rank": "Gründer",
      "mcname": "_Mausi_",
      "join_date": "2021-01-15",
      "achievements": [...]
    }
  ]
}

Achievements Endpoint

Das Achievement-System belohnt Mitglieder für Meilensteine und Aktivitäten.

GET /api_achievements.php?member_id={id}

Gibt alle Achievements eines Mitglieds zurück. Automatische Filterung: Nur das höchste Zeit-Achievement wird angezeigt (Hierarchie-System).

Parameter	Typ	Beschreibung
member_id	integer required	ID des Mitglieds

Response

JSON Response

{
  "success": true,
  "achievements": [
    {
      "id": 5,
      "name": "1 Jahr Mitglied",
      "description": "365 Tage Treue",
      "icon": "bi-calendar-check",
      "unlocked_at": "2022-01-15",
      "unlocked_by": "SYSTEM"
    }
  ]
}

POST /api_grant_achievement.php

Vergibt ein Achievement an ein Mitglied. Erfordert Admin-Authentifizierung.

Parameter	Typ	Beschreibung
member_id	integer required	ID des Mitglieds
achievement_id	integer required	ID des Achievements

Images Endpoint

Liefert Galerie-Bilder für die öffentliche Bildergalerie.

GET /get_images.php

Gibt alle Galerie-Bilder mit Pfad und optionaler Caption zurück.

Response

JSON Response

[
  {
    "src": "images/gallery/battle_2024.webp",
    "caption": "Schlacht um den Nordturm"
  },
  {
    "src": "images/gallery/event_winter.webp",
    "caption": "Winterfest 2024"
  }
]

Stats Endpoint

Statistiken und Metriken der Nation.

GET /api_stats.php

Aggregierte Statistiken: Mitgliederzahl, Achievement-Verteilung, Wachstumsdaten.

Response

JSON Response

{
  "total_members": 42,
  "active_members": 38,
  "veterans": 12,
  "achievements_granted": 156,
  "growth_this_month": 3
}

Error Codes

Standardisierte Fehler-Responses für konsistente Fehlerbehandlung.

Code	Status	Beschreibung
200	OK	Erfolgreiche Anfrage
400	Bad Request	Fehlende oder ungültige Parameter
401	Unauthorized	Authentifizierung erforderlich
404	Not Found	Ressource nicht gefunden
500	Server Error	Interner Serverfehler

Error Response Format

{
  "success": false,
  "error": "Invalid member_id parameter",
  "code": 400
}

Rate Limiting

Zum Schutz der Infrastruktur gelten folgende Limits:

Endpoint-Typ	Limit	Zeitfenster
Public GET	100 Requests	pro Minute
Admin POST	30 Requests	pro Minute

Bei Überschreitung wird HTTP 429 (Too Many Requests) zurückgegeben.