Die Public API ermöglicht es Drittanbietern, Discord-Bots oder eigenen Web-Anwendungen, sicher und performant auf öffentliche Daten des NRW Roleplay Systems zuzugreifen. Der Zugriff erfolgt rein lesend und ist durch ein striktes Rate-Limiting geschützt.Documentation Index
Fetch the complete documentation index at: https://docs.nrw-roleplay.de/llms.txt
Use this file to discover all available pages before exploring further.
Authentifizierung
Um die API nutzen zu können, benötigst du einen gültigen API-Key. Dieser wird dir von der Projektleitung zugewiesen.API-Key erhalten
Fordere deinen Key für dein Projekt an. Jeder Key ist einem festen Client (z. B. “Discord Bot”) zugewiesen.
Alternativ kann der Key auch über den Query-Parameter
?key=DEIN_KEY übergeben werden. Wir empfehlen jedoch aus Sicherheitsgründen die Verwendung des Headers.Endpunkte und Abfragen
Die Basis-URL für alle Anfragen lautet:https://systems.nrw-roleplay.de/API/api.php
Wichtig: Die API akzeptiert ausschließlich GET-Anfragen. Andere Methoden (POST, PUT, DELETE) werden sofort mit einem 405 Method Not Allowed blockiert.
System-Status
Prüft die Erreichbarkeit und gibt die aktuelle API-Version sowie einen Zeitstempel zurück.| Parameter | Wert |
|---|---|
type | sys_status |
Verfügbare Datentypen
Um Daten abzurufen, musst du den Typ (type) und in den meisten Fällen die entsprechende Server-ID (guild_id) als Query-Parameter anhängen. Beispiel: ?type=stats&guild_id=123456789.
| Typ | Beschreibung |
|---|---|
list_guilds | Listet alle aktiven Server-IDs auf, die das System nutzen (keine guild_id nötig). |
config | Allgemeine Server-Einstellungen und Modul-Status. |
stats | Server-Statistiken (Usercounts, Aktivität). |
teams | Aktuelle Teamlisten und Rollenbesetzungen. |
punishments / unban | Öffentliche Sanktionslisten und Entbannungs-Daten. |
tickets | Öffentliche Metadaten des Ticket-Systems. |
autos / verify | Systemdaten zu Fahrzeugen und Verifizierungen. |
shifts / shift_configs | Aktuelle Schichten und Dienst-Konfigurationen. |
personensystem | Daten aus dem Einwohnermeldeamt / Personensystem. |
blacklist | Globale Blacklist-Einträge des Netzwerks (keine guild_id nötig). |
announcements | Globale System-Nachrichten und Updates (keine guild_id nötig). |
Rate Limiting & Sicherheit
Um die Stabilität des Systems zu gewährleisten, unterliegt jeder API-Key einem RPM-Limit (Requests Per Minute).Limits nach Client-Typ
Limits nach Client-Typ
- Discord Bot: 120 Anfragen / Minute
- Web Dashboard: 60 Anfragen / Minute
- Entwickler-Key: 30 Anfragen / Minute
Rate-Limit Header
Rate-Limit Header
Du kannst deinen aktuellen Status über die HTTP-Response-Header auslesen:
X-RateLimit-Limit: Dein maximales Limit.X-RateLimit-Remaining: Verbleibende Anfragen im aktuellen Fenster.Retry-After: Sekunden, die du warten musst, falls du das Limit überschritten hast (HTTP 429).
Fehlerbehandlung
Die API nutzt standardisierte HTTP-Statuscodes zur Fehlermeldung:400 Bad Request
Fehlender oder ungültiger
type Parameter.401 Unauthorized
API-Key fehlt oder ist ungültig.
404 Not Found
Die angeforderten Daten oder die Gilde existieren nicht.
405 Method Not Allowed
Es wurde eine andere Methode als GET verwendet.
429 Too Many Requests
Rate-Limit überschritten. Bitte
Retry-After Header beachten.Integration v4.0
Neu in Version 4.0:
- Strikter Read-Only Schutz — Sämtliche modifizierenden Methoden werden auf Webserver-Ebene blockiert.
- Anti-Caching Mechanismen — Neue Header (
Cache-Control: no-store...) garantieren, dass dynamische Daten (wie Shifts oder Stats) immer in Echtzeit und nicht aus dem Browser-Cache geladen werden. - Sichere Parameter — Eingehende Parameter werden nun strikt via Regex bereinigt, um Path-Traversal zu verhindern.
- Performance Boost — Die API nutzt nun moderne PHP 8 Match-Strukturen für ein noch schnelleres Routing der Anfragen.