Rozhraní — úplný seznam

Tenhle seznam není psaný z hlavy. Mod si dokument o sobě generuje ze svých vlastních rout (GET /v1/openapi.json), takže se nemůže mýlit v tom, co existuje — a tahle stránka je z něj vytažená příkazem scripts/reference.sh v repozitáři modu. Když si nejsi jistý, ptej se svého serveru, ne téhle stránky.

Platí pro 0.1.1. Cest je 44.

/keystone key new muj-nastroj status.read players.read

Klíč se vypíše jednou a nikdy víc. Dej mu tu nejužší sadu scopů, která odvede práci: skript, co hlídá, jestli server běží, chce status.read a nic dalšího.

curl -sS -H "Authorization: Bearer ks_…" \
  http://127.0.0.1:25586/v1/status

GET bere parametry v adrese, POST je posílá jako formulář:

curl -sS -X POST -H "Authorization: Bearer ks_…" \
  -d "player=Honza" -d "group=vip" -d "for=30d" \
  -d "note=koupeno na webu" \
  http://127.0.0.1:25586/v1/players/group

[api]
enabled = true
address = "127.0.0.1"
port = 25586

Nic není vidět zvenčí. Panel i tvoje skripty běží na tom samém stroji.

Nechej mod na loopbacku a přines si port k sobě:

ssh -L 25586:127.0.0.1:25586 ty@tvuj-server
curl -sS -H "Authorization: Bearer ks_…" http://127.0.0.1:25586/v1/status

Nic se nevystavuje a /keystone panel se otevře u tebe v prohlížeči.

/keystone set keystone.api.address 0.0.0.0
/keystone set keystone.api.reachable-at 192.168.1.100

První říká, kde se poslouchá, druhé, jakou adresu si má mod napsat do odkazu na editor a do openapi.json — 0.0.0.0 je dobrá odpověď na to první a nepoužitelná na to druhé. K tomu pusť port jen z LAN, ne ze světa:

sudo ufw allow from 192.168.1.0/24 to any port 25586 proto tcp

Nech mod na loopbacku a postav před něj něco, co umí TLS:

location /keystone/ {
    proxy_pass http://127.0.0.1:25586/;
    proxy_set_header Host $host;
}

/keystone set keystone.api.reachable-at keystone.tvujserver.eu

Nikdy nedávej api.address na veřejnou adresu bez TLS. Klíč jde v hlavičce a přes http:// po internetu ho přečte kdokoliv po cestě. A API umí všechno, co umí mod.

curl -N -H "Authorization: Bearer ks_…" \
  http://127.0.0.1:25586/v1/events

Drží spojení otevřené a píše do něj události, jak se dějí (text/event-stream). Tři řádky v prohlížeči:

const events = new EventSource('/v1/events');
events.onmessage = (e) => console.log(JSON.parse(e.data));

Ověřuje se jako všechno ostatní a bez klíče odpoví 404.

curl -sS -H "Authorization: Bearer ks_…" \
  "http://127.0.0.1:25586/v1/catalog?of=minecraft:item&like=diamond&limit=20"

Parametry:

Na serveru, který není v online režimu, jméno napsané do formuláře nedokazuje nic. Pořadí je tohle:

# 1. Kdo je ten člověk ve hře — podle Discordu, kterým se přihlásil na webu
curl -sS -H "Authorization: Bearer ks_…" \
  "http://127.0.0.1:25586/v1/discord/links?discord=123456789012345678"

# 2. Doruč mu, co si koupil, s datem konce
curl -sS -X POST -H "Authorization: Bearer ks_…" \
  -d "player=Honza" -d "group=vip" -d "for=30d" -d "note=objednávka 4821" \
  http://127.0.0.1:25586/v1/players/group

Hodnost skončí sama v ten den. Nikdo si nemusí pamatovat, že ji má sundat.

Parametry:

Parametry: /v1/settings bere setting (celé jméno, třeba operations.restart.when) a value; /v1/settings/rollback bere version.

curl -sS -X POST -H "Authorization: Bearer ks_…" \
  -d "setting=operations.restart.when" -d "value=every 6h" \
  http://127.0.0.1:25586/v1/settings

Co všechno jde nastavit, je na stránce Všechna nastavení.

Parametry: /v1/assistant/ask bere question; /v1/assistant/decide bere proposal (která) a answer (yes nebo no).

Když stavíš addon v Javě, přes HTTP nemluvíš. Kompiluješ proti keystone-api, který jede uvnitř toho samého jaru (META-INF/jarjar/eu.stygion.keystone.api-<verze>.jar) a nemá žádné vlastní závislosti, ani logovací. Registruje se přes něj vlastní modul, příkaz, oprávnění, zdroj hodností — a taky vlastní route, která pak vypadá v tomhle seznamu a v openapi.json úplně stejně jako ty naše.

Každá změna přes rozhraní je auditní řádek: který klíč, co, kdy — a každé odmítnutí taky. Klíč, který opakovaně zkouší, co nesmí, je jediná stopa, kterou o převzaté integraci dostaneš. Citlivé příkazy se maskují z auditu, konzole i logu.