Die REST-API
231 Aufrufe · 09.10.2026 23:13 Verlauf

Die REST-API

Die API lässt ein Programm — den Discord-Bot von NeoFrag Reborn, ein Skript, eine Integration — die Daten der Seite lesen und in ihr Forum oder ihren Bugtracker schreiben, ohne Browser. Sie antwortet in JSON, unter versionierten Adressen (/api/v1/…), und nimmt nur Programme an, die einen von einem Administrator angelegten Zugriffsschlüssel haben.

Sie wird vom Modul API geliefert, das optional ist: System → Themes & Addons, um es zu installieren, falls es das nicht ist.

Einen Zugriffsschlüssel anlegen

Verwaltung → API → Neuer Schlüssel. Gib ihm einen Namen, der sagt, wer ihn nutzt („Discord-Bot“), und hake nur die Rechte an, die das Programm braucht:

Recht Was es öffnet
members:read Die Mitglieder (nach Kennung oder nach verknüpftem Discord-Konto) und die Liste der Gruppen
forum:read Das Forum: seine Struktur, seine Themen, seine Nachrichten — geschützte Kategorien eingeschlossen
forum:write Im Namen eines Mitglieds oder eines Discord-Kontos ins Forum schreiben: ein Thema anlegen, antworten, eine Nachricht dieses Autors bearbeiten oder löschen
events:read Der Ereignis-Feed (neues Thema, neue Nachricht, Gruppenwechsel…)
bugtracker:read Der Bugtracker: seine Tickets und ihre Kommentare
bugtracker:write Im Namen eines Mitglieds oder eines Discord-Kontos in den Bugtracker schreiben: ein Ticket eröffnen, kommentieren, einen Kommentar dieses Autors bearbeiten oder löschen
discord:bot Der Discord-Bot der Seite sein: seine Konfiguration — Discord-Token eingeschlossen —, sein Zustand, sein Protokoll. Das Discord-Modul legt diesen Schlüssel selbst an (siehe Der Discord-Bot)

Der Schlüssel (nfr_ gefolgt von 40 Zeichen) wird nur einmal angezeigt, direkt nach dem Anlegen: Die Seite behält nur seinen Fingerabdruck. Ein verlorener Schlüssel lässt sich nicht wiederfinden — man widerruft ihn und legt einen anderen an. Die Liste der Schlüssel zeigt ihre letzte Nutzung und die Adresse, von der sie kam.

Die API aufrufen

Jede Anfrage trägt den Schlüssel im Header Authorization:

curl -H "Authorization: Bearer nfr_…" https://deine-seite.example/api/v1/status

Eine erfolgreiche Antwort verpackt ihre Daten in data:

{
    "data": {
        "site": "Mein Team",
        "version": "1.2.9",
        "api": "v1",
        "token": { "name": "Discord-Bot", "scopes": ["members:read", "forum:read"] }
    }
}

Texte (Titel von Foren und Gruppen) kommen in der Standardsprache der Seite und im Klartext: „é“, nicht é, wie die Seite sie für ihre Seiten speichert. Umgekehrt wird, was ein Programm schreibt, gespeichert wie das, was man auf der Seite schreibt: Ein Tag in einem Titel wird angezeigt, nicht ausgeführt.

Die Adressen der Version 1

Methode und Adresse Recht Gibt zurück
GET /api/v1/status keins Die Seite, ihre Version und den verwendeten Schlüssel mit seinen Rechten — um eine Konfiguration zu prüfen
GET /api/v1/members/{id} members:read Ein Mitglied: id, username, url, avatar, registration_date, groups (Gruppenschlüssel), discord (id, username) oder null
GET /api/v1/members/discord/{id} members:read Das Mitglied, das dieses Discord-Konto verknüpft hat (gleiche Form)
GET /api/v1/groups members:read Die Gruppen: key, title, color, icon, hidden, auto (eine von der Seite berechnete Gruppe), members (Anzahl)
GET /api/v1/forums forum:read Die Kategorien, jede mit ihren Foren und deren Unterforen: id, title, description, icon, topics, replies, url, und link für ein Forum, das woandershin verweist
GET /api/v1/forum/topics/{id} forum:read Ein Thema: forum_id, title, author (id, username) oder null, external_author (provider, external_id, name) für ein nicht verknüpftes Discord-Konto, created_at, announce, locked, prefix, first_message_id, last_message_id, solution_message_id, replies, views, url
GET /api/v1/forum/messages/{id} forum:read Eine Nachricht: topic_id, forum_id, author, external_author, created_at, is_first, deleted, html (wie das Forum sie zeigt), text (Klartext), url — eine gelöschte Nachricht gibt deleted: true ohne Inhalt zurück
GET /api/v1/events?after={id}&limit={n} events:read Der Ereignis-Feed (siehe unten)
POST /api/v1/forum/topics forum:write Legt ein Thema an (siehe „Ins Forum schreiben“) und gibt es mit 201 zurück
POST /api/v1/forum/topics/{id}/messages forum:write Antwortet auf ein Thema und gibt die Nachricht mit 201 zurück
POST /api/v1/forum/images?name={name} forum:write Behält ein Bild für eine Nachricht: Der Body der Anfrage ist das Bild (JPEG, PNG, GIF oder WebP, höchstens 5 MB, geprüft und neu kodiert wie die des Editors). Gibt path zurück — in den Inhalt zu schreiben, ![name](path) — und url, beim ersten Mal mit 201; dasselbe erneut geschickte Bild gibt dieselbe Adresse zurück
PATCH /api/v1/forum/messages/{id} forum:write Bearbeitet eine Nachricht — nur im Namen ihres Autors
DELETE /api/v1/forum/messages/{id} forum:write Verschiebt eine Nachricht in den Papierkorb des Forums — im Namen ihres Autors; nicht die erste Nachricht eines Themas
PATCH /api/v1/forum/topics/{id} forum:write Ändert das Präfix eines Themas: prefix_id (null für keins); gibt das Thema zurück
GET /api/v1/bugtracker/tickets?after={id}&limit={n}&open=1 bugtracker:read Die Tickets in der Reihenfolge ihrer Nummer, stapelweise (standardmäßig 50, höchstens 100); nur die offenen mit open=1. Gibt tickets, next (den nächsten Cursor) und more zurück
GET /api/v1/bugtracker/tickets/{id} bugtracker:read Ein Ticket: title, description, type (bug, feature, question, other), priority, status, duplicate_of, author, created_at, updated_at, url
GET /api/v1/bugtracker/comments/{id} bugtracker:read Ein Kommentar: ticket_id, content, author, external_author (ein nicht verknüpftes Discord-Konto), status_change, created_at
POST /api/v1/bugtracker/tickets bugtracker:write Eröffnet ein Ticket (siehe „In den Bugtracker schreiben“) und gibt es mit 201 zurück
POST /api/v1/bugtracker/tickets/{id}/comments bugtracker:write Kommentiert ein Ticket und gibt den Kommentar mit 201 zurück
PATCH /api/v1/bugtracker/comments/{id} bugtracker:write Bearbeitet einen Kommentar — nur im Namen seines Autors
DELETE /api/v1/bugtracker/comments/{id} bugtracker:write Löscht einen Kommentar — nur im Namen seines Autors

Die Adressen bugtracker/* antworten mit 404 module_unavailable, wenn der Bugtracker nicht installiert ist.

Die Adressen des Discord-Bots

Sie verlangen das Recht discord:bot und antworten mit 404 module_unavailable, wenn das Discord-Modul nicht installiert ist. Sie dienen dem Bot von NeoFrag Reborn; ein anderes Programm hat keine Verwendung für sie.

Methode und Adresse Gibt zurück
GET /api/v1/discord/config Die Konfiguration des Bots: token (sein Discord-Token, entschlüsselt), client_id, guild_id, running, channels, roles (jede mit group_key, role_id sowie name und color ihrer Gruppe), tags (Präfix ↔ Tag), features (jede Funktion an oder aus, und ihre Einstellungen), lang, i18n (die Übersetzungen der Texte, die er zeigt), version (die Nummer, die sich bei jeder Einstellung ändert), events_cursor, api_token_id, texts
POST /api/v1/discord/heartbeat Das Lebenszeichen des Bots (version, connected, intents, guild: der Server, seine Kanäle, ihre Tags und seine Rollen; features: seine Funktionen und ihre Einstellungen; texts: seine zu übersetzenden Texte; events_cursor); gibt running, version und die wartenden commands zurück, jeder mit type (restart, resync, setup, setup-undo) und data
POST /api/v1/discord/logs Zeilen seines Protokolls: entries, jede mit level, message, template und args (die Vorlage, die die Verwaltung übersetzt)
GET /api/v1/discord/members Die Mitglieder, die ihr Discord verknüpft haben: discord_id, member_id, username, groups
GET /api/v1/discord/links?type=…&site_id=… (oder discord_id=…) Die Verknüpfung eines Elements der Seite mit seinem Gegenstück auf Discord — type: topic, message, ticket oder comment; 404 link_not_found, wenn es keine gibt
POST /api/v1/discord/links Behält eine Verknüpfung: type, site_id, discord_id; mit replace: true weicht die, die das Element der Seite schon hatte (ein Ticket, das den Kanal wechselt)
POST /api/v1/discord/links/lookup Welche dieser Discord-Elemente (type, discord_ids, höchstens 500) schon ihr Gegenstück auf der Seite haben: found
POST /api/v1/discord/link-request /forum account link: ein Einmal-Link zur Seite (url, expires_in), oder linked und member, wenn dieses Discord schon verknüpft ist
POST /api/v1/discord/unlink /forum account unlink: hebt die Verknüpfung dieses Discords auf (409 not_linked, only_login_method)
GET /api/v1/discord/identity/{discord_id} Wie dieses Konto im Forum erscheint: linked und member, oder mode (public, guest, custom), name, custom_name, custom_change_at
PATCH /api/v1/discord/identity/{discord_id} /forum visibility: mode, username, custom_name (409 linked, invalid_name, name_taken, too_soon)
POST /api/v1/discord/setup, POST /api/v1/discord/setup/undo Der Bericht einer Einrichtung des Servers oder ihrer Rücknahme: Die Seite setzt oder entfernt die Zuordnungen
GET /api/v1/discord/timed-roles?discord_id=…&due=1 Die laufenden befristeten Rollen — die eines Mitglieds, oder mit due=1 die abgelaufenen: timed_roles, jede mit timed_id, discord_id, username, role_id, expires_at (Unix-Zeitstempel), given_by, given_by_name, reason
POST /api/v1/discord/timed-roles Gibt oder verlängert eine befristete Rolle: discord_id, username, role_id, duration (Sekunden, von 60 bis zu einem Jahr), given_by, given_by_name, reason; 409 role_mapped für eine mit einer Gruppe der Seite verknüpfte Rolle
DELETE /api/v1/discord/timed-roles/{id} Entfernt eine befristete Rolle aus der Liste
GET /api/v1/discord/sanctions Die Sanktionen, die gerade auf Discord gelten — seitenweite Stummschaltungen und Sperren, in Kraft, eines verknüpften Mitglieds: sanctions, jede mit sanction_id, user_id, discord_id, type (mute, ban_temp, ban_perm), expires_at (Unix-Zeitstempel oder null), origine (site oder discord)
POST /api/v1/discord/sanctions Meldet eine auf Discord verhängte Sanktion: type, executor_discord_id, target_discord_id, duration_seconds, reason; gibt 201 sanction_id, requires_approval zurück. Ablehnungen: 422 invalid_type, 403 executor_unlinked, 404 target_unlinked, 403 forbidden (der Moderator hat dieses Recht auf der Seite nicht), 403 refused (Hierarchie, man selbst)
POST /api/v1/discord/sanctions/{id}/revoke Hebt eine von Discord gekommene Sanktion auf: executor_discord_id; 404 not_found, 409 site_sanction (sie wird auf der Seite aufgehoben), 403 forbidden
GET /api/v1/discord/collectives Die Kollektive, die ihren Bereich auf Discord wollen: collectives, jedes mit collective_id, name, group_key (der Schlüssel seiner Gruppe), role_id und channel_id (oder null, solange sie nicht existieren)
POST /api/v1/discord/collectives/{id} Die Rolle oder der Kanal, die der Bot gerade angelegt hat: role_id, channel_id — die Rolle wird zur Zuordnung der Gruppe des Kollektivs; 404 not_found, 422 invalid_id

Ins Forum schreiben

Die API schreibt immer im Namen eines Autors, angegeben im JSON-Body der Anfrage:

  • "author": { "member_id": 7 } — ein Mitglied der Seite;
  • "author": { "discord": { "id": "123456789012345678", "username": "Spitzname", "avatar": "https://cdn.discordapp.com/…" } } — ein Discord-Konto. Ist es mit einem Mitglied verknüpft (Anmeldung über Discord), wird die Nachricht unter diesem Mitglied veröffentlicht: sein echtes Konto, sein Benutzername, sein Avatar. Sonst wird sie unter der Discord-Identität der Person veröffentlicht: ihr Discord-Name, mit dem Discord-Logo markiert, ohne Link zu einem Profil der Seite.
curl -X POST -H "Authorization: Bearer nfr_…" -H "Content-Type: application/json" \
     -d '{"forum_id": 3, "title": "Meine Frage", "content": "**Hallo** zusammen", "author": {"discord": {"id": "123456789012345678", "username": "Spitzname"}}}' \
     https://deine-seite.example/api/v1/forum/topics
Feld Für Inhalt
forum_id Thema Das Forum, in dem veröffentlicht wird (kein Forum, das woandershin verweist)
title Thema 1 bis 100 Zeichen
prefix_id Thema Optional: ein Themenpräfix des Forums
content alles Der Text, 1 bis 20.000 Zeichen
format alles markdown (Standard — das Format von Discord) oder html
reply_to Antwort Optional: die Nachricht, auf die geantwortet wird
author alles Der Autor (oben)

Markdown wird in HTML umgewandelt; jedes hineingeschmuggelte HTML wird maskiert, und HTML durchläuft dieselbe Bereinigung wie der Rest der Seite. Der Autor muss das Recht haben, ins Forum zu schreiben, wie auf der Seite (sonst 403 forum_forbidden): ein Mitglied oder ein verknüpftes Discord-Konto über seine Rechte an der Kategorie; ein Discord-Konto ohne Konto der Seite über die der Mitglieder. Ein gesperrtes Thema lehnt Antworten ab (409 topic_locked). Bearbeiten oder Löschen verlangt denselben Autor wie die Nachricht (sonst 403 not_author): Wer sie geschrieben hat, korrigiert sie. Eine fehlerhafte Anfrage gibt 400 invalid_json zurück; ein ungültiges Feld 422 validation_failed mit den Details in error.fields.

Die Moderationssanktionen gelten auch über die API: Ein im Forum (oder auf der Seite) stummgeschaltetes oder gesperrtes Mitglied schreibt dort nicht (403 sanctioned), und ein Mitglied ohne Recht auf externe Links veröffentlicht keinen Text, der welche trägt (403 links_forbidden). error.message nennt die Sanktion, um sie dem Autor zu zeigen. Ein Discord-Konto ohne Konto der Seite hat keine Sanktion.

Die Schreibvorgänge der API erscheinen im Ereignis-Feed mit source.token_id: Ein Programm, das das Forum anderswohin kopiert, erkennt so, was es selbst geschrieben hat.

In den Bugtracker schreiben

Wie im Forum schreibt die API im Namen eines Autors (author, gleiche Form). Ein Ticket gehört einem Mitglied: Ein Discord-Konto, das mit keinem Mitglied verknüpft ist, wird abgelehnt (409 not_linked). Ein Kommentar dagegen kann von einem nicht verknüpften Discord-Konto kommen: Er erscheint unter dessen Discord-Namen. Die Moderationssanktionen gelten wie im Forum (403 sanctioned, links_forbidden).

Feld Für Inhalt
title Ticket 1 bis 200 Zeichen
description Ticket Der Text, 1 bis 20.000 Zeichen
type Ticket bug (Standard), feature, question oder other
content Kommentar Der Text, 1 bis 20.000 Zeichen
author alles Der Autor

Einen Kommentar bearbeiten oder löschen verlangt denselben Autor (sonst 403 not_author).

Der Ereignis-Feed

Statt die ganze Seite in regelmäßigen Abständen abzufragen, liest ein Programm den Ereignis-Feed: „Was ist seit Ereignis Nr. X passiert?“. Die Seite muss es nicht kontaktieren — das Programm öffnet keinen Port.

curl -H "Authorization: Bearer nfr_…" "https://deine-seite.example/api/v1/events?after=0&limit=100"
{
    "data": {
        "events": [
            {
                "id": 41,
                "type": "forum.post.created",
                "data": { "message_id": 512, "topic_id": 88, "forum_id": 3, "user_id": 7, "is_starter": false },
                "source": null,
                "created_at": "2026-10-01T17:42:03+02:00"
            }
        ],
        "next": 41,
        "more": false
    }
}

Behalte den Wert von next und gib ihn beim nächsten Mal als after zurück. Solange more true ist, gibt es sofort weitere Ereignisse zu lesen. Ereignisse bleiben 30 Tage im Feed.

type data
forum.topic.created topic_id, message_id, forum_id, user_id, identity_id
forum.post.created message_id, topic_id, forum_id, user_id, identity_id, is_starter (die erste Nachricht eines Themas)
forum.post.edited message_id, topic_id, forum_id, user_id, is_topic
forum.post.deleted message_id, topic_id, forum_id, is_topic, hard_delete, deleted_by
forum.topic.split source_topic_id, new_topic_id, message_ids, forum_id
forum.topics.merged source_topic_id, target_topic_id, forum_id
forum.topic.prefixed topic_id, forum_id, prefix_id — das Präfix eines Themas hat sich geändert
bugtracker.ticket.created ticket_id, user_id, type
bugtracker.ticket.updated ticket_id, status, type, fields (die geänderten Felder)
bugtracker.ticket.deleted ticket_id
bugtracker.comment.created, .edited, .deleted comment_id, ticket_id (und user_id beim Anlegen)
user.groups.changed user_id — das Mitglied für seine aktuellen Gruppen erneut lesen
user.discord.linked, user.discord.unlinked user_id, discord_id — ein Discord-Konto wurde gerade verknüpft oder getrennt
discord.collective.removed collective_id, role_id, channel_id — ein Kollektiv verlässt Discord (gelöscht oder sein Feld abgehakt): seine Rolle ist zu löschen
discord.sanction.created, .approved, .revoked sanction_id, user_id, discord_id, type, expires_at, origine — eine seitenweite Stummschaltung oder Sperre eines verknüpften Mitglieds ist gerade in Kraft getreten (verhängt oder bestätigt) oder aufgehoben worden

Ein Ereignis trägt nur Kennungen: Der Inhalt wird über die Adressen oben gelesen, wenn er gebraucht wird (eine inzwischen gelöschte Nachricht gibt deleted: true zurück). source sagt, woher die Änderung kam: null für die Seite, { "token_id": … } für einen mit einem API-Schlüssel ausgeführten Schreibvorgang — ein Programm erkennt so seine eigenen Schreibvorgänge und kopiert sie nicht ein zweites Mal.

Die Fehler

Ein Fehler gibt den passenden HTTP-Code und ein Objekt error zurück, dessen code stabil ist (ein Programm kann sich darauf verlassen) und dessen message lesbar ist:

{ "error": { "code": "forbidden", "message": "Cette clé n’a pas le droit « forum:read »." } }
HTTP code Wann
401 unauthorized Schlüssel fehlt, unbekannt oder widerrufen (mit dem Header WWW-Authenticate: Bearer)
403 forbidden, not_author, forum_forbidden, sanctioned, links_forbidden Der Schlüssel hat das von der Adresse verlangte Recht nicht; der angegebene Autor ist nicht der der Nachricht; der Autor darf in diesem Forum nicht schreiben; eine Moderationssanktion hindert ihn daran oder verbietet ihm den Link, den sein Text trägt
400 invalid_json Der Body der Anfrage ist kein gültiges JSON
404 not_found, member_not_found, topic_not_found, message_not_found, ticket_not_found, comment_not_found, link_not_found, module_unavailable Unbekannte Adresse; fehlendes Element; Modul (das Forum, der Bugtracker, Discord) nicht installiert
409 topic_locked, is_first_message, not_linked, role_mapped, … Gesperrtes Thema; Löschen der ersten Nachricht eines Themas; Discord-Konto nicht verknüpft; mit einer Gruppe verknüpfte Rolle — und die eigenen Ablehnungen der Adressen des Bots, dort genannt
422 validation_failed Ein Feld ist ungültig — die Details stehen in error.fields
405 method_not_allowed Falsche Methode (der Header Allow sagt, welche)
429 too_many_requests Ratenbegrenzung erreicht (der Header Retry-After sagt, in wie vielen Sekunden man es erneut versucht)

Die Ratenbegrenzung

Ein Schlüssel kann 120 Anfragen pro Minute stellen; jede Antwort sagt, wie viele bleiben (X-RateLimit-Remaining). Darüber hinaus antwortet die API eine Minute lang mit 429. Eine IP-Adresse, die in einer Minute 20 abgelehnte Schlüssel schickt, wird fünf Minuten gesperrt: Nichts erlaubt, die API zu bombardieren, um einen Schlüssel zu erraten.

Sicherheit

  • Die Seite behält nur den Fingerabdruck der Schlüssel: Ein Datenbankleck liefert keinen brauchbaren Schlüssel.
  • Ein Schlüssel öffnet nur seine Rechte und wird mit einem Klick widerrufen; jedes Anlegen und jeder Widerruf wird im Audit-Log eingetragen (Benutzer → Audit-Log).
  • Die API setzt weder Cookie noch Sitzung und liefert nie eine Seite aus: nur JSON.
  • Bewahre den Schlüssel auf der Serverseite auf (Umgebungsvariable, nicht versionierte Datei), nie in veröffentlichtem Code oder in einer Webseite.

Meine Cookies verwalten

Die Website speichert nur die Cookies, die sie zum Funktionieren braucht: Dafür ist Ihre Zustimmung nicht erforderlich. Die anderen Dienste gehören anderen Unternehmen; sie werden nur geladen, wenn Sie sie akzeptieren. Ihre Wahl wird sechs Monate gespeichert, und Sie können sie jederzeit ändern.

Für die Website erforderlich Immer aktiv

  • __Host-session Hält Sie angemeldet und schützt die Formulare vor betrügerischen Übermittlungen. Bis zum Schließen des Browsers; ein Jahr mit „Angemeldet bleiben“
  • nf_consent Speichert die Entscheidungen, die Sie in diesem Fenster treffen. 6 Monate
  • nf_fuseau Zeigt Datum und Uhrzeit in Ihrer Zeitzone an. 1 Jahr
  • Browser-Speicher Speichert Ihre Wahl zwischen Tag- und Nachtmodus sowie die für die Artikelliste gewählte Darstellung. Bis Sie ihn leeren

Videos

In Seiten eingebettete Videos: Der Player stammt von der Plattform, die Ihre IP-Adresse erhält und ihre Cookies speichern kann.

Musik

In Seiten eingebettete Titel und Playlists: Der Player stammt von der Plattform, die Ihre IP-Adresse erhält und ihre Cookies speichern kann.