API HTTP

Des scripts et des sites (tableaux de bord, bots Discord, boutiques) peuvent lire et modifier le serveur par une API JSON servie par FXServer sur le port du jeu :

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

L'activer

L'API est désactivée par défaut. Activez-la dans /nay, sur la page Nayretis : API HTTP (ApiEnabled). Tant qu'elle est désactivée, chaque route répond 503 api_disabled. Taille maximale d'une requête (Ko) (ApiMaxBodyKb) limite le corps des requêtes (1024 Ko par défaut).

Jetons

Créez les jetons dans l'onglet API de /nay (le jeton n'est affiché qu'une fois : copiez-le à ce moment) ou depuis la console du serveur :

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

Un jeton ressemble à nay_<id>_<secret>. Seule son empreinte SHA-256 est enregistrée. Chaque jeton a ses scopes, des adresses autorisées facultatives (IPv4, IPv6 ou plages CIDR), une limite de requêtes par minute et une expiration facultative.

Les scopes sont <resource>.<scope>, avec des jokers : nay_car_wash.* donne toutes les routes d'un script, * donne tout. Chaque script liste ses routes et ses scopes sur sa propre page, par exemple Car Wash.

Requêtes

• Envoyez Authorization: Bearer <token>.
• Les corps sont en JSON (Content-Type: application/json) avec un Content-Length. Les corps découpés (chunked) sont refusés.
• Après 10 authentifications ratées en une minute, les requêtes sans jeton valide de cette adresse sont refusées pendant 5 minutes. Les jetons valides continuent de fonctionner.
• Derrière un proxy inverse, réglez nay:apiTrustedProxies (voir HTTPS). Sinon, tous les appelants partagent l'adresse du proxy.

Chaque réponse est en JSON avec un en-tête X-Request-Id :

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

Statut	Code	Signification
400	unexpected_body, invalid_json, invalid_request	Corps envoyé à une route sans corps, JSON invalide, ou Content-Length mal formé.
401	unauthorized	Jeton absent, inconnu, révoqué ou expiré.
403	forbidden, ip_not_allowed	Le jeton n'a pas le scope, ou l'adresse n'est pas autorisée pour lui.
404 / 405	not_found, method_not_allowed	Route inconnue, ou mauvaise méthode sur une route connue.
411	length_required	Tout Transfer-Encoding (corps découpé).
413	payload_too_large	Corps au-delà de ApiMaxBodyKb. Un Content-Length annoncé au-delà de 10 Mo est refusé avant la lecture du corps.
415	unsupported_media_type	Corps qui n'est pas en application/json.
422	invalid_request, unknown_parameter, invalid_value	Paramètre, requête ou corps refusé à la validation (details.path et details.reason).
429	rate_limited, too_many_failures	Jeton au-delà de sa limite par minute, ou adresse bloquée. Voir Retry-After.
500	internal_error	La route a échoué. Voir la console du serveur.
503	api_disabled, not_ready	API désactivée, ou ressource encore en démarrage (Retry-After).
504	timeout	La route n'a pas répondu en 10 secondes. Elle continue de tourner : un changement peut encore s'appliquer après le 504, relisez donc l'état avant de réessayer.

Routes de nay_lib

Méthode	Route	Scope	Données
GET	/nay_lib/v1/status	nay.status	Nom du serveur, joueurs, joueurs max, framework, inventaire, target, ressources Nayretis et versions.
GET	/nay_lib/v1/players	nay.players	Joueurs connectés : id, nom, personnage, identifiant, métier.
GET	/nay_lib/v1/settings/:resource	nay.settings plus <resource>.config ou nay.config	Réglages d'un script avec leurs valeurs.
PUT	/nay_lib/v1/settings/:resource/:key	idem	Modifie un réglage. Corps { "value": ... }.
DELETE	/nay_lib/v1/settings/:resource/:key	idem	Remet un réglage à sa valeur par défaut.
GET	/nay_lib/v1/audit	nay.audit	Journal, 50 lignes par page. Requête resource, action, actor, from et to (secondes Unix), page.

Chaque appel qui modifie quelque chose est écrit dans le journal (api.call, acteur api:<token label>).

HTTPS

FXServer ne parle qu'en HTTP simple : n'importe qui sur le chemin peut lire un jeton envoyé ainsi. Placez un proxy inverse avec un certificat devant l'API et n'exposez que les routes utilisées. Indiquez ensuite à nay_lib les proxys de confiance, pour que les adresses autorisées et les limites s'appliquent à l'adresse réelle du client, lue dans X-Forwarded-For :

set nay:apiTrustedProxies "127.0.0.1"

La valeur est une liste d'adresses ou de plages CIDR séparées par des virgules.

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 (certificat obtenu automatiquement) :

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