API MineListu pre majiteľov serverov

API MineListu umožňuje vášmu serveru zistiť, či hráč hlasoval, vydať odmenu práve raz a načítať verejné štatistiky. Všetky endpointy vracajú JSON a používajú obyčajné HTTPS požiadavky GET, takže fungujú z akéhokoľvek jazyka.

Ako získať API kľúč

Pridajte svoj server, potvrďte ho ako svoj a otvorte panel majiteľa. API kľúč nájdete v nastaveniach servera. Držte ho v súkromí, pretože identifikuje váš server. Ak unikne, vygenerujte v paneli nový a aktualizujte plugin alebo skript.

Základná adresa všetkých endpointov je https://minelist.eu.

Kontrola hlasu

GET /api/v1/vote?key=API_KEY&username=NICK

Vráti, či hráč dnes hlasoval a či už bola odmena vyzdvihnutá.

{"voted":true,"claimed":false,"next_vote_utc":"2026-10-31T00:00:00Z"}

voted je true, ak má nick pre váš server hlas v aktuálnom dni UTC.
claimed je true, ak ste hlas už označili ako vyzdvihnutý.
next_vote_utc je čas, kedy môže hráč hlasovať znova.

Vyzdvihnutie hlasu

GET /api/v1/vote/claim?key=API_KEY&username=NICK

Označí dnešný hlas ako vyzdvihnutý. Zavolajte ho tesne pred vydaním odmeny, aby si hráč nemohol odmenu vziať dvakrát. Možné odpovede:

Odpoveď	Význam
`{"voted":true,"claimed":true}`	Hlas bol platný a je teraz vyzdvihnutý. Vydajte odmenu.
`{"voted":true,"claimed":false,"already_claimed":true}`	Hlas už bol vyzdvihnutý skôr. Nevydávajte nič.
`{"voted":false,"claimed":false}`	Hráč dnes nehlasoval.

Zoznam hlasov za tento mesiac

GET /api/v1/votes?key=API_KEY

Vráti všetky hlasy, ktoré váš server v aktuálnom mesiaci dostal. Hodí sa na mesačné odmeny najlepším hlasujúcim a rebríčky na vašom webe.

Verejné štatistiky servera

GET /api/v1/server/<slug>

Tento endpoint kľúč nepotrebuje. Slug je posledná časť adresy servera na MineListe. Vrátené polia:

Pole	Popis
`name`	Názov servera
`url`	Web servera
`ip`	Adresa na pripojenie
`online`	Či posledná kontrola uspela
`players`	Počet hráčov pri poslednej kontrole
`max_players`	Počet slotov
`version`	Verzia servera
`votes_month`	Hlasy za tento mesiac
`votes_total`	Hlasy od pridania servera
`uptime_30`	Dostupnosť za posledných 30 dní v percentách
`rating`	Priemerné hodnotenie
`last_check`	Čas poslednej kontroly

Príklad s curl

Takto vyzerá celá logika v shelli. To isté urobí akýkoľvek jazyk, ktorý vie poslať HTTP požiadavku, napríklad Java, PHP, Python alebo Node.js.

curl -s "https://minelist.eu/api/v1/vote/claim?key=API_KEY&username=Steve"

Spracujte JSON, a ak je claimed true, spustite príkaz s odmenou, napríklad give Steve diamond 3.

Podpora NuVotifieru

Ak chcete odmeny okamžite a bez dopytovania, MineList vie hlasy posielať na váš server cez NuVotifier. Podporujeme obe verzie protokolu. Verzia 1 používa verejný kľúč RSA, verzia 2 token.

Nainštalujte NuVotifier na server a reštartujte ho.
V paneli majiteľa zadajte hostiteľa, port (predvolený je 8192) a verejný kľúč (v1) alebo token (v2).
Kliknite na Poslať testovací hlas a skontrolujte, že ho server zapíše do logu.

Ak test zlyhá, overte, že je port Votifieru otvorený vo firewalle a že ste kľúč skopírovali bez medzier a zalomení riadkov.

Živý banner

Každý server má živý banner s rozmermi 468x60 pixelov so stavom a počtom hráčov:

https://minelist.eu/banner/<slug>.png

Príklad vloženia do HTML:

<a href="https://minelist.eu/sk/server/vas-slug">
  <img src="https://minelist.eu/banner/vas-slug.png" width="468" height="60" alt="Hlasujte za nás na MineListe">
</a>

Odporúčaný postup

Verejné štatistiky ukladajte do cache aspoň na minútu a nevolajte API pri každom zobrazení stránky.
API kľúč nikdy nevkladajte do kódu na strane prehliadača ani do verejného repozitára.
Endpoint na vyzdvihnutie volajte iba raz na jednu odmenu.