HTTP-API

Skripte und Websites (Dashboards, Discord-Bots, Shops) können den Server über eine JSON-API lesen und ändern, die FXServer auf dem Spielport bereitstellt:

http://<server ip>:<port>/<resource>/v1/<route>

Aktivieren

Die API ist standardmäßig aus. Aktiviere sie in /nay auf der Seite Nayretis: HTTP-API (ApiEnabled). Solange sie aus ist, antwortet jede Route mit 503 api_disabled. Maximale Anfragegröße (KB) (ApiMaxBodyKb) begrenzt den Anfrageinhalt (standardmäßig 1024 KB).

Tokens

Erstelle Tokens im Tab API von /nay (das Token wird nur einmal angezeigt: kopiere es sofort) oder über die Serverkonsole:

nay_api_token create <label> <scope...>
nay_api_token list
nay_api_token revoke <id>

Ein Token sieht so aus: nay_<id>_<secret>. Gespeichert wird nur sein SHA-256-Hash. Jedes Token hat seine Scopes, optional erlaubte Adressen (IPv4, IPv6 oder CIDR-Bereiche), ein Anfragelimit pro Minute und ein optionales Ablaufdatum.

Scopes haben die Form <resource>.<scope>, mit Platzhaltern: nay_car_wash.* gibt jede Route eines Skripts frei, * gibt alles frei. Jedes Skript listet seine Routen und Scopes auf seiner eigenen Seite, zum Beispiel Car Wash.

Anfragen

• Sende Authorization: Bearer <token>.
• Anfrageinhalte sind JSON (Content-Type: application/json) mit einem Content-Length. Inhalte in Chunks werden abgelehnt.
• Nach 10 fehlgeschlagenen Authentifizierungen innerhalb einer Minute werden Anfragen ohne gültiges Token von dieser Adresse 5 Minuten lang abgelehnt. Gültige Tokens funktionieren weiter.
• Hinter einem Reverse Proxy setzt du nay:apiTrustedProxies (siehe HTTPS). Sonst teilen sich alle Aufrufer die Adresse des Proxys.

Jede Antwort ist JSON mit einem Header X-Request-Id:

{ "ok": true, "data": { } }
{ "ok": false, "error": { "code": "forbidden", "message": "This token does not allow this route", "details": { } } }

Status	Code	Bedeutung
400	unexpected_body, invalid_json, invalid_request	Inhalt an eine Route ohne Inhalt gesendet, Inhalt kein gültiges JSON oder fehlerhafter Content-Length.
401	unauthorized	Token fehlt, ist unbekannt, widerrufen oder abgelaufen.
403	forbidden, ip_not_allowed	Dem Token fehlt der Scope, oder die Adresse ist für dieses Token nicht erlaubt.
404 / 405	not_found, method_not_allowed	Unbekannte Route oder falsche Methode für eine bekannte Route.
411	length_required	Jedes Transfer-Encoding (Inhalt in Chunks).
413	payload_too_large	Inhalt größer als ApiMaxBodyKb. Ein angekündigter Content-Length über 10 MB wird abgelehnt, bevor der Inhalt gelesen wird.
415	unsupported_media_type	Inhalt, der nicht application/json ist.
422	invalid_request, unknown_parameter, invalid_value	Parameter, Query oder Inhalt besteht die Prüfung nicht (details.path und details.reason).
429	rate_limited, too_many_failures	Token über seinem Limit pro Minute oder Adresse gesperrt. Siehe Retry-After.
500	internal_error	Die Route ist fehlgeschlagen. Siehe Serverkonsole.
503	api_disabled, not_ready	API aus oder Ressource startet noch (Retry-After).
504	timeout	Die Route hat nicht innerhalb von 10 Sekunden geantwortet. Sie läuft weiter: Eine Änderung kann nach dem 504 noch angewendet werden, lies den Zustand also erneut, bevor du es noch einmal versuchst.

Routen von nay_lib

Methode	Route	Scope	Daten
GET	/nay_lib/v1/status	nay.status	Servername, Spieler, maximale Spieler, Framework, Inventar, Target, Nayretis Ressourcen und Versionen.
GET	/nay_lib/v1/players	nay.players	Verbundene Spieler: ID, Name, Charakter, Kennung, Job.
GET	/nay_lib/v1/settings/:resource	nay.settings plus <resource>.config oder nay.config	Einstellungen eines Skripts mit ihren Werten.
PUT	/nay_lib/v1/settings/:resource/:key	wie oben	Ändert eine Einstellung. Inhalt { "value": ... }.
DELETE	/nay_lib/v1/settings/:resource/:key	wie oben	Setzt eine Einstellung auf ihren Standardwert zurück.
GET	/nay_lib/v1/audit	nay.audit	Protokoll, 50 Einträge pro Seite. Query resource, action, actor, from und to (Unix-Sekunden), page.

Jeder Aufruf, der etwas ändert, wird ins Protokoll geschrieben (api.call, Urheber api:<token label>).

HTTPS

FXServer spricht nur unverschlüsseltes HTTP: Jeder auf dem Übertragungsweg kann ein so gesendetes Token mitlesen. Setze einen Reverse Proxy mit Zertifikat vor die API und gib nur die Routen frei, die du nutzt. Teile nay_lib dann mit, welchen Proxys es vertrauen soll, damit erlaubte Adressen und Anfragelimits für die echte Client-Adresse aus X-Forwarded-For gelten:

set nay:apiTrustedProxies "127.0.0.1"

Der Wert ist eine durch Kommas getrennte Liste von Adressen oder CIDR-Bereichen.

nginx:

server {
	listen 443 ssl;
	server_name api.example.com;
	ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
	ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;

	location ~ ^/(nay_lib|nay_car_wash)/v1/ {
		proxy_pass http://127.0.0.1:30120;
		proxy_set_header X-Forwarded-For $remote_addr;
		client_max_body_size 1m;
	}
}

Caddy (Zertifikat wird automatisch bezogen):

api.example.com {
	@nayretis path_regexp ^/(nay_lib|nay_car_wash)/v1/
	reverse_proxy @nayretis 127.0.0.1:30120
}