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.

---

Než něco zavoláš

1. Vyrob si klíč

/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.

2. Zavolej

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

3. Co znamenají odpovědi

Kód	Co to je
200	Vyšlo to.
400	Něco v požadavku nesedělo, a odpověď říká co.
403	Klíč je pravý, ale nemá scope, který ta cesta chce.
404	Taková cesta není — nebo nemáš klíč vůbec. Odpovídá se stejně schválně: volající bez klíče se o tomhle serveru nedozví nic.
429	Překročil jsi, co ten klíč smí za minutu.

---

Kudy se k tomu dostaneš

Jen z téhle mašiny (výchozí, a je to ta bezpečná volba)

[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.

Z tvého počítače, přes tunel (doporučené u hostovaného serveru)

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.

Z domácí sítě

/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

Zvenčí, přes reverzní proxy nebo tunel

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.

---

Živý proud

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.

---

Stav a měření

Metoda	Cesta	Scope	K čemu
GET	/v1/status	status.read	Co tenhle server je a jak mu je
GET	/v1/metrics	status.read	Co dělá právě teď a poslední čtvrthodina
GET	/v1/metrics/history	status.read	Po minutách, tak daleko dozadu, jak to nastavení drží
GET	/v1/entities	status.read	Co je načtené ve světě a co by úklid teď sebral
GET	/v1/gate	status.read	Jestli je server otevřený a kolik míst se drží stranou
GET	/v1/catalog	status.read	Všechno, co tenhle pack načetl: registry, obsah jednoho (?of=minecraft:item, s from/limit/like), nebo jeho tagy (&tags=true)
GET	/v1/bench	server.read	Zátěžové běhy, které tenhle server udělal (?id= pro jeden celý)
GET	/v1/openapi.json	status.read	Tenhle dokument

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

Lidi a oprávnění

Metoda	Cesta	Scope	K čemu
GET	/v1/players	players.read	Kdo je právě online
GET	/v1/progress	players.read	Co jeden hráč udělal, nebo žebříček jednoho počítadla
GET	/v1/skins	players.read	Co má kdo na sobě a odkud to je
GET	/v1/accounts	players.read	Kolik účtů má heslo a kdo čeká, až se prokáže
GET	/v1/bans	players.read	Každý ban, který ještě stojí
GET	/v1/tickets	players.read	Tickety (?id= pro jeden se vším, co se v něm řeklo, ?player=)
GET	/v1/votes	players.read	Hlasy, které serveru přišly, a jak je na tom party cíl (?player=, ?limit=)
GET	/v1/discord/links	players.read	Které herní účty má jeden Discord uživatel propojené (?discord=<id>)
GET	/v1/groups	permissions.read	Každá skupina oprávnění, nejtěžší první
POST	/v1/players/check	permissions.read	Jestli někdo něco smí — a které pravidlo o tom rozhodlo
POST	/v1/players/group	permissions.write	Dej někoho do skupiny, nebo mu v ní prodluž čas
POST	/v1/players/perk	perks.write	Dej někomu pojmenovanou výhodu, případně do data
POST	/v1/players/grants	perks.read	Co jeden hráč drží, odkud to má a kdy to končí

Parametry:

Cesta	Bere
/v1/players/check	player — jméno někoho online · permission — na které oprávnění se ptáš
/v1/players/grants	player — jméno někoho online
/v1/players/group	player · group — id skupiny · for — 30d, 12h, 90m, nebo vynech pro napořád · note — proč, pro toho, kdo to bude číst později
/v1/players/perk	player · perk — co dostane · for · note

Jak z toho udělat obchod

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.

Provoz

Metoda	Cesta	Scope	K čemu
GET	/v1/operations	operations.read	Co je naplánované a kolik zbývá
GET	/v1/operations/history	operations.read	Co v poslední době proběhlo, nejnovější první
POST	/v1/operations/run	operations.run	Spusť jednu teď, nebo se zpožděním, s obvyklými varováními
POST	/v1/operations/cancel	operations.run	Odvolej, co je rozjeté, a vrať se k rozvrhu
POST	/v1/gate/maintenance	operations.run	Zavři server na údržbu, nebo ho zase otevři
GET	/v1/backups	backup.read	Každá záloha, nejnovější první, i s tím, co stojí na disku
POST	/v1/backups/restore	backup.restore	Vrať zálohu — připraví se a udělá při příštím startu

Parametry:

Cesta	Bere
/v1/operations/run	operation — která · in — za kolik vteřin, 0 hned
/v1/operations/cancel	operation — která
/v1/gate/maintenance	closed — true zavřít, false otevřít · reason — co se děje, uvidí to každý, kdo se pokusí připojit · until — kdy to má skončit, tvými slovy
/v1/backups/restore	backup — jméno zálohy, nebo cancel pro odvolání

Nastavení a záznam

Metoda	Cesta	Scope	K čemu
GET	/v1/settings	settings.read	Každé nastavení, co který modul deklaroval, co to je a co v tom stojí
POST	/v1/settings	settings.write	Změň jedno. Odmítne se i s důvodem, když hodnota neodpovídá tomu, co ta věc je
GET	/v1/settings/history	settings.read	Každá změna, nejnovější první, i s tím, jaká byla hodnota předtím
POST	/v1/settings/rollback	settings.write	Vrať, co jedna verze změnila. Vrácení je samo verze, takže jde vrátit taky
POST	/v1/reload	settings.write	Přečti znovu všechny soubory s nastavením. Nic se nerestartuje a nikoho to nevyhodí
GET	/v1/audit	audit.read	Kdo co přes tohle rozhraní změnil, nejnovější první. Čtení se nezapisuje, změny a odmítnutí ano
GET	/v1/keys	keys.read	Klíče, které tenhle server vydal, bez jejich tajemství

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í.

Konzole, chat a Discord

Metoda	Cesta	Scope	K čemu
GET	/v1/console	console.read	Poslední řádky, co server vypsal, nejstarší první. Drží se v paměti, ne v databázi
GET	/v1/chat	chat.read	Poslední, co padlo v chatu, nejstarší první
GET	/v1/events	events.read	Živý proud událostí
GET	/v1/discord	server.read	Jestli je most na Discord připojený a jak moc je pozadu

Asistent

Metoda	Cesta	Scope	K čemu
POST	/v1/assistant/ask	assistant.write	Zeptej se ho. Odpověď přijde tímhle voláním
POST	/v1/assistant/incident	assistant.write	Podej mu poslední úsek konzole a chatu a zeptej se, co vypadá špatně
POST	/v1/assistant/decide	assistant.write	Souhlas s navrženou změnou, nebo ji nech být
GET	/v1/assistant/proposals	assistant.read	Změny, které chce udělat a nikdo o nich zatím nerozhodl
GET	/v1/assistant/threads	assistant.read	Konverzace, které byly, nejnovější první
GET	/v1/assistant/thread	assistant.read	Jedna konverzace, nejstarší zpráva první

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

---

Addony na JVM

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.

---

Co se zapisuje

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.