MineList API szervertulajdonosoknak

A MineList API segítségével a szervered ellenőrizheti, hogy egy játékos szavazott-e, pontosan egyszer adhat jutalmat, és lekérheti a nyilvános statisztikákat. Minden végpont JSON-t ad vissza, és egyszerű HTTPS GET kéréseket használ, ezért bármilyen nyelvből működik.

Az API-kulcs megszerzése

Add hozzá a szerveredet, igényeld meg, és nyisd meg a tulajdonosi panelt. Az API-kulcsot a szerverbeállítások oldalán találod. Tartsd titokban, mert ez azonosítja a szerveredet. Ha kiszivárog, generálj egy újat a panelben, és frissítsd a bővítményedet vagy a szkriptedet.

Az összes végpont alapcíme https://minelist.eu.

Szavazat ellenőrzése

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

Megmutatja, hogy a játékos szavazott-e ma, és hogy a jutalmat már beváltották-e.

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

A voted értéke true, ha a nicknek van szavazata a szerveredre az aktuális UTC-napon.
A claimed értéke true, ha ezt a szavazatot már beváltottnak jelölted.
A next_vote_utc az az időpont, amikor a játékos újra szavazhat.

Szavazat beváltása

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

A mai szavazatot beváltottnak jelöli. Közvetlenül a jutalom kiadása előtt hívd meg, hogy a játékos ne kaphassa meg kétszer. Lehetséges válaszok:

Válasz	Jelentés
`{"voted":true,"claimed":true}`	A szavazat érvényes volt, és most beváltottnak számít. Add ki a jutalmat.
`{"voted":true,"claimed":false,"already_claimed":true}`	A szavazatot korábban már beváltották. Ne adj ki semmit.
`{"voted":false,"claimed":false}`	A játékos ma nem szavazott.

A havi szavazatok listázása

GET /api/v1/votes?key=API_KEY

Visszaadja az összes szavazatot, amelyet a szervered az aktuális hónapban kapott. Hasznos a hónap legjobb szavazóinak jutalmazásához és a saját weboldaladon megjelenő ranglistákhoz.

Nyilvános szerverstatisztikák

GET /api/v1/server/<slug>

Ehhez a végponthoz nem kell kulcs. A slug a szerver MineListen lévő címének utolsó része. Példa a válasz mezőire:

Mező	Leírás
`name`	A szerver neve
`url`	A szerver weboldala
`ip`	Csatlakozási cím
`online`	Sikeres volt-e az utolsó ellenőrzés
`players`	Az utolsó ellenőrzéskor online lévő játékosok
`max_players`	Játékoshelyek száma
`version`	A szerver verziója
`votes_month`	Szavazatok ebben a hónapban
`votes_total`	Szavazatok a szerver hozzáadása óta
`uptime_30`	Az elmúlt 30 nap elérhetősége százalékban
`rating`	Átlagos értékelés
`last_check`	Az utolsó ellenőrzés időpontja

Példa curllel

Ez a teljes logika shell formában. Bármelyik nyelv, amely tud HTTP kérést küldeni, például a Java, a PHP, a Python vagy a Node.js, ugyanezt teszi.

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

Dolgozd fel a JSON-t, és ha a claimed értéke true, futtasd le a jutalomparancsot, például a give Steve diamond 3 parancsot.

NuVotifier támogatás

Ha lekérdezés nélküli, azonnali jutalmakat szeretnél, a MineList a NuVotifieren keresztül elküldheti a szavazatokat a szervered számára. Mindkét protokollverzió támogatott. Az 1-es verzió RSA nyilvános kulcsot használ, a 2-es verzió tokent.

Telepítsd a NuVotifiert a szerveredre, és indítsd újra.
A tulajdonosi panelben add meg a hostot, a portot (alapértelmezés szerint 8192) és a nyilvános kulcsot (v1) vagy a tokent (v2).
Nyomd meg a Teszt szavazat küldése gombot, és ellenőrizd, hogy a szervered naplózza a szavazatot.

Ha a teszt sikertelen, győződj meg róla, hogy a Votifier port nyitva van a tűzfalban, és hogy a kulcsot szóközök vagy sortörések nélkül másoltad be.

Élő banner

Minden szervernek van egy 468x60 pixeles élő bannere, amely az aktuális állapotot és a játékosszámot mutatja:

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

HTML beágyazási példa:

<a href="https://minelist.eu/hu/server/a-te-slugod">
  <img src="https://minelist.eu/banner/a-te-slugod.png" width="468" height="60" alt="Szavazz ránk a MineListen">
</a>

Bevált gyakorlatok

A nyilvános statisztikákat legalább egy percig tárold gyorsítótárban ahelyett, hogy minden oldalmegtekintéskor lekérdeznéd az API-t.
Soha ne tedd az API-kulcsot kliensoldali kódba vagy nyilvános tárolóba.
A beváltási végpontot jutalmanként csak egyszer használd.