API HTTP

Skrypty i strony internetowe (panele, boty Discord, sklepy) mogą odczytywać i zmieniać stan serwera przez API JSON udostępniane przez FXServer na porcie gry:

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

Włączenie

API jest domyślnie wyłączone. Włącz je w /nay, na stronie Nayretis: API HTTP (ApiEnabled). Dopóki jest wyłączone, każda trasa odpowiada 503 api_disabled. Maksymalny rozmiar żądania (KB) (ApiMaxBodyKb) ogranicza treść żądań (domyślnie 1024 KB).

Tokeny

Tokeny tworzy się w zakładce API w /nay (token jest pokazywany tylko raz: skopiuj go od razu) albo z konsoli serwera:

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

Token wygląda tak: nay_<id>_<secret>. Przechowywany jest tylko jego skrót SHA-256. Każdy token ma swoje scope'y, opcjonalne dozwolone adresy (IPv4, IPv6 lub zakresy CIDR), limit żądań na minutę i opcjonalną datę wygaśnięcia.

Scope'y mają postać <resource>.<scope> i obsługują symbole wieloznaczne: nay_car_wash.* daje dostęp do wszystkich tras skryptu, * do wszystkiego. Każdy skrypt wymienia swoje trasy i scope'y na własnej stronie, na przykład Car Wash.

Żądania

• Wysyłaj Authorization: Bearer <token>.
• Treść żądania to JSON (Content-Type: application/json) z nagłówkiem Content-Length. Treści przesyłane w kawałkach (chunked) są odrzucane.
• Po 10 nieudanych uwierzytelnieniach w ciągu minuty żądania bez ważnego tokena z tego adresu są odrzucane przez 5 minut. Ważne tokeny nadal działają.
• Za reverse proxy ustaw nay:apiTrustedProxies (zobacz HTTPS). W przeciwnym razie wszyscy wywołujący dzielą adres proxy.

Każda odpowiedź to JSON z nagłówkiem X-Request-Id:

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

Status	Kod	Znaczenie
400	unexpected_body, invalid_json, invalid_request	Treść wysłana do trasy bez treści, treść niebędąca poprawnym JSON albo błędny Content-Length.
401	unauthorized	Brak tokena albo token nieznany, unieważniony lub wygasły.
403	forbidden, ip_not_allowed	Token nie ma wymaganego scope'a albo adres nie jest dla niego dozwolony.
404 / 405	not_found, method_not_allowed	Nieznana trasa albo zła metoda dla znanej trasy.
411	length_required	Dowolny Transfer-Encoding (treść chunked).
413	payload_too_large	Treść większa niż ApiMaxBodyKb. Zapowiedziany Content-Length powyżej 10 MB jest odrzucany przed odczytaniem treści.
415	unsupported_media_type	Treść inna niż application/json.
422	invalid_request, unknown_parameter, invalid_value	Parametr, zapytanie lub treść nie przechodzi walidacji (details.path i details.reason).
429	rate_limited, too_many_failures	Token przekroczył limit na minutę albo adres jest zablokowany. Zobacz Retry-After.
500	internal_error	Trasa zakończyła się błędem. Sprawdź konsolę serwera.
503	api_disabled, not_ready	API wyłączone albo zasób jeszcze się uruchamia (Retry-After).
504	timeout	Trasa nie odpowiedziała w ciągu 10 sekund. Dalej działa: zmiana może zostać zastosowana już po 504, więc przed ponowną próbą odczytaj aktualny stan.

Trasy nay_lib

Metoda	Trasa	Scope	Dane
GET	/nay_lib/v1/status	nay.status	Nazwa serwera, gracze, maksymalna liczba graczy, framework, ekwipunek, target, zasoby Nayretis i ich wersje.
GET	/nay_lib/v1/players	nay.players	Połączeni gracze: id, nazwa, postać, identyfikator, zawód.
GET	/nay_lib/v1/settings/:resource	nay.settings oraz <resource>.config lub nay.config	Ustawienia skryptu z ich wartościami.
PUT	/nay_lib/v1/settings/:resource/:key	jak wyżej	Zmienia ustawienie. Treść { "value": ... }.
DELETE	/nay_lib/v1/settings/:resource/:key	jak wyżej	Przywraca domyślną wartość ustawienia.
GET	/nay_lib/v1/audit	nay.audit	Dziennik zmian, 50 wpisów na stronę. Zapytanie resource, action, actor, from i to (sekundy Unix), page.

Każde wywołanie, które coś zmienia, trafia do dziennika zmian (api.call, autor api:<token label>).

HTTPS

FXServer obsługuje tylko zwykłe HTTP: każdy po drodze może odczytać przesłany w ten sposób token. Umieść przed API reverse proxy z certyfikatem i udostępniaj tylko trasy, których używasz. Następnie wskaż nay_lib, którym proxy ufać, aby dozwolone adresy i limity żądań dotyczyły prawdziwego adresu klienta pobranego z X-Forwarded-For:

set nay:apiTrustedProxies "127.0.0.1"

Wartość to lista adresów lub zakresów CIDR oddzielonych przecinkami.

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 (certyfikat uzyskiwany automatycznie):

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