API HTTP

Los scripts y las webs (paneles de control, bots de Discord, tiendas) pueden leer y modificar el servidor mediante una API JSON servida por FXServer en el puerto del juego:

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

Activarla

La API está desactivada por defecto. Actívala en /nay, en la página Nayretis: API HTTP (ApiEnabled). Mientras está desactivada, todas las rutas responden 503 api_disabled. Tamaño máximo de solicitud (KB) (ApiMaxBodyKb) limita el cuerpo de las solicitudes (1024 KB por defecto).

Tokens

Crea los tokens en la pestaña API de /nay (el token se muestra una sola vez: cópialo en ese momento) o desde la consola del servidor:

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

Un token tiene la forma nay_<id>_<secret>. Solo se guarda su hash SHA-256. Cada token tiene sus scopes, direcciones permitidas opcionales (IPv4, IPv6 o rangos CIDR), un límite de solicitudes por minuto y una caducidad opcional.

Los scopes tienen la forma <resource>.<scope>, con comodines: nay_car_wash.* da todas las rutas de un script, * lo da todo. Cada script indica sus rutas y scopes en su propia página, por ejemplo Car Wash.

Solicitudes

• Envía Authorization: Bearer <token>.
• Los cuerpos son JSON (Content-Type: application/json) con un Content-Length. Los cuerpos fragmentados (chunked) se rechazan.
• Tras 10 autenticaciones fallidas en un minuto, las solicitudes sin token válido desde esa dirección se rechazan durante 5 minutos. Los tokens válidos siguen funcionando.
• Detrás de un proxy inverso, define nay:apiTrustedProxies (consulta HTTPS). Si no, todos los clientes comparten la dirección del proxy.

Cada respuesta es JSON con una cabecera X-Request-Id:

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

Estado	Código	Significado
400	unexpected_body, invalid_json, invalid_request	Cuerpo enviado a una ruta sin cuerpo, cuerpo que no es JSON válido, o Content-Length mal formado.
401	unauthorized	Token ausente, desconocido, revocado o caducado.
403	forbidden, ip_not_allowed	El token no tiene el scope, o la dirección no está permitida para él.
404 / 405	not_found, method_not_allowed	Ruta desconocida, o método incorrecto en una ruta conocida.
411	length_required	Cualquier Transfer-Encoding (cuerpo fragmentado).
413	payload_too_large	Cuerpo por encima de ApiMaxBodyKb. Un Content-Length anunciado de más de 10 MB se rechaza antes de leer el cuerpo.
415	unsupported_media_type	Cuerpo que no es application/json.
422	invalid_request, unknown_parameter, invalid_value	Parámetro, query o cuerpo que no pasa la validación (details.path y details.reason).
429	rate_limited, too_many_failures	Token por encima de su límite por minuto, o dirección bloqueada. Consulta Retry-After.
500	internal_error	La ruta ha fallado. Consulta la consola del servidor.
503	api_disabled, not_ready	API desactivada, o recurso todavía arrancando (Retry-After).
504	timeout	La ruta no respondió en 10 segundos. Sigue ejecutándose: un cambio puede aplicarse aun después del 504, así que vuelve a leer el estado antes de reintentar.

Rutas de nay_lib

Método	Ruta	Scope	Datos
GET	/nay_lib/v1/status	nay.status	Nombre del servidor, jugadores, máximo de jugadores, framework, inventario, target, recursos Nayretis y sus versiones.
GET	/nay_lib/v1/players	nay.players	Jugadores conectados: id, nombre, personaje, identificador, trabajo.
GET	/nay_lib/v1/settings/:resource	nay.settings más <resource>.config o nay.config	Ajustes de un script con sus valores.
PUT	/nay_lib/v1/settings/:resource/:key	igual	Cambia un ajuste. Cuerpo { "value": ... }.
DELETE	/nay_lib/v1/settings/:resource/:key	igual	Restablece un ajuste a su valor por defecto.
GET	/nay_lib/v1/audit	nay.audit	Registro de auditoría, 50 entradas por página. Query resource, action, actor, from y to (segundos Unix), page.

Cada llamada que cambia algo se anota en el registro de auditoría (api.call, autor api:<token label>).

HTTPS

FXServer solo habla HTTP sin cifrar: cualquiera en el camino puede leer un token enviado así. Coloca delante de la API un proxy inverso con certificado y expón solo las rutas que uses. Después indica a nay_lib en qué proxies confiar, para que las direcciones permitidas y los límites de solicitudes se apliquen a la dirección real del cliente, tomada de X-Forwarded-For:

set nay:apiTrustedProxies "127.0.0.1"

El valor es una lista de direcciones o rangos CIDR separados por comas.

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 (certificado obtenido automáticamente):

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