Skip to main content
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.

​
Authentifizierung

Um die API nutzen zu können, benötigst du einen gültigen API-Key. Dieser wird dir von der Projektleitung zugewiesen.
1

API-Key erhalten

Fordere deinen Key für dein Projekt an. Jeder Key ist einem festen Client (z. B. “Discord Bot”) zugewiesen.
2

Request autorisieren

Sende deinen Key bei jeder Anfrage im Header mit.
3

Daten empfangen

Die API antwortet im standardisierten, UTF-8 kodierten JSON-Format.
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.

​
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.

​
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

  • Discord Bot: 120 Anfragen / Minute
  • Web Dashboard: 60 Anfragen / Minute
  • Entwickler-Key: 30 Anfragen / Minute
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.