API HTTP

Scripts e sites (painéis, bots do Discord, lojas) podem ler e alterar o servidor através de uma API JSON servida pelo FXServer na porta do jogo:

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

Ativar a API

A API vem desativada por predefinição. Ative-a no /nay, na página Nayretis: API HTTP (ApiEnabled). Enquanto estiver desativada, todas as rotas respondem 503 api_disabled. Tamanho máximo do pedido (KB) (ApiMaxBodyKb) limita o corpo dos pedidos (1024 KB por predefinição).

Tokens

Crie tokens no separador API do /nay (o token só é mostrado uma vez: copie-o nesse momento) ou a partir da consola do servidor:

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

Um token tem o formato nay_<id>_<secret>. Só é guardado o respetivo hash SHA-256. Cada token tem os seus âmbitos, endereços permitidos opcionais (IPv4, IPv6 ou intervalos CIDR), um limite de pedidos por minuto e uma expiração opcional.

Os âmbitos têm o formato <resource>.<scope>, com caracteres universais: nay_car_wash.* dá acesso a todas as rotas de um script, * dá acesso a tudo. Cada script lista as suas rotas e âmbitos na respetiva página, por exemplo Car Wash.

Pedidos

• Envie Authorization: Bearer <token>.
• Os corpos são JSON (Content-Type: application/json) com um Content-Length. Os corpos em chunks são recusados.
• Depois de 10 autenticações falhadas num minuto, os pedidos sem token válido vindos desse endereço são recusados durante 5 minutos. Os tokens válidos continuam a funcionar.
• Atrás de um proxy inverso, defina nay:apiTrustedProxies (consulte HTTPS). Caso contrário, todos os clientes partilham o endereço do proxy.

Cada resposta é JSON com um cabeçalho X-Request-Id:

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

Status	Código	Significado
400	unexpected_body, invalid_json, invalid_request	Corpo enviado a uma rota sem corpo, corpo que não é JSON válido, ou Content-Length mal formado.
401	unauthorized	Token em falta, desconhecido, revogado ou expirado.
403	forbidden, ip_not_allowed	O token não tem o âmbito, ou o endereço não é permitido para ele.
404 / 405	not_found, method_not_allowed	Rota desconhecida, ou método errado numa rota conhecida.
411	length_required	Qualquer Transfer-Encoding (corpo em chunks).
413	payload_too_large	Corpo acima de ApiMaxBodyKb. Um Content-Length anunciado acima de 10 MB é recusado antes de o corpo ser lido.
415	unsupported_media_type	Corpo que não é application/json.
422	invalid_request, unknown_parameter, invalid_value	Parâmetro, query ou corpo que não passa na validação (details.path e details.reason).
429	rate_limited, too_many_failures	Token acima do limite por minuto, ou endereço bloqueado. Consulte Retry-After.
500	internal_error	A rota falhou. Consulte a consola do servidor.
503	api_disabled, not_ready	API desativada, ou recurso ainda a arrancar (Retry-After).
504	timeout	A rota não respondeu em 10 segundos. Continua a ser executada: uma alteração pode ainda ser aplicada depois do 504, por isso leia o estado de novo antes de tentar outra vez.

Rotas do nay_lib

Método	Rota	Âmbito	Dados
GET	/nay_lib/v1/status	nay.status	Nome do servidor, jogadores, máximo de jogadores, framework, inventário, target, recursos Nayretis e versões.
GET	/nay_lib/v1/players	nay.players	Jogadores ligados: id, nome, personagem, identificador, profissão.
GET	/nay_lib/v1/settings/:resource	nay.settings mais <resource>.config ou nay.config	Definições de um script com os respetivos valores.
PUT	/nay_lib/v1/settings/:resource/:key	o mesmo	Altera uma definição. Corpo { "value": ... }.
DELETE	/nay_lib/v1/settings/:resource/:key	o mesmo	Repõe uma definição no valor predefinido.
GET	/nay_lib/v1/audit	nay.audit	Registo, 50 linhas por página. Query resource, action, actor, from e to (segundos Unix), page.

Cada chamada que altera algo fica gravada no registo (api.call, autor api:<token label>).

HTTPS

O FXServer só fala HTTP simples: qualquer pessoa no caminho pode ler um token enviado por ele. Coloque um proxy inverso com certificado à frente da API e exponha apenas as rotas que usa. Depois indique ao nay_lib em que proxies confiar, para que os endereços permitidos e os limites de pedidos se apliquem ao endereço real do cliente, obtido a partir de X-Forwarded-For:

set nay:apiTrustedProxies "127.0.0.1"

O valor é uma lista de endereços ou intervalos CIDR separados por vírgulas.

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 obtido automaticamente):

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