MineList API za vlasnike servera

MineList API omogućuje tvom serveru da provjeri je li igrač glasao, da dodijeli nagradu točno jednom i da čita javnu statistiku. Svi endpointi vraćaju JSON i koriste obične HTTPS GET zahtjeve pa rade iz bilo kojeg programskog jezika.

Kako dobiti API ključ

Dodaj svoj server, preuzmi ga i otvori panel za vlasnike. API ključ prikazan je na stranici s postavkama servera. Čuvaj ga privatnim jer identificira tvoj server. Ako procuri, generiraj novi u panelu i ažuriraj svoj plugin ili skriptu.

Osnovna adresa svih endpointa je https://minelist.eu.

Provjera glasa

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

Pokazuje je li igrač danas glasao i je li nagrada već preuzeta.

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

voted je true ako nick ima glas za tvoj server u tekućem UTC danu.
claimed je true ako je taj glas već označen kao preuzet.
next_vote_utc je vrijeme kada igrač može ponovno glasati.

Preuzimanje glasa

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

Označava današnji glas kao preuzet. Pozovi ga neposredno prije nego podijeliš nagradu kako igrač ne bi mogao uzeti nagradu dvaput. Mogući odgovori:

Odgovor	Značenje
`{"voted":true,"claimed":true}`	Glas je bio valjan i sada je preuzet. Daj nagradu.
`{"voted":true,"claimed":false,"already_claimed":true}`	Glas je već ranije preuzet. Ne daj ništa.
`{"voted":false,"claimed":false}`	Igrač danas nije glasao.

Popis glasova ovog mjeseca

GET /api/v1/votes?key=API_KEY

Vraća sve glasove koje je tvoj server primio u tekućem mjesecu. Koristan je za mjesečne nagrade najaktivnijim glasačima i za ljestvice na tvojoj web-stranici.

Javna statistika servera

GET /api/v1/server/<slug>

Ovaj endpoint ne treba ključ. Slug je zadnji dio adrese servera na MineListu. Primjeri polja u odgovoru:

Polje	Opis
`name`	Naziv servera
`url`	Web-stranica servera
`ip`	Adresa za spajanje
`online`	Je li posljednja provjera uspjela
`players`	Igrači online pri posljednjoj provjeri
`max_players`	Broj mjesta za igrače
`version`	Verzija servera
`votes_month`	Glasovi ovaj mjesec
`votes_total`	Glasovi od dodavanja servera
`uptime_30`	Dostupnost u posljednjih 30 dana u postocima
`rating`	Prosječna ocjena
`last_check`	Vrijeme posljednje provjere

Primjer s curlom

Ovo je cijela logika u obliku shell naredbe. Svaki jezik koji može poslati HTTP zahtjev, na primjer Java, PHP, Python ili Node.js, radi isto.

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

Parsiraj JSON i, ako je claimed true, izvrši svoju naredbu za nagradu, na primjer give Steve diamond 3.

Podrška za NuVotifier

Ako želiš trenutačne nagrade bez stalnog propitivanja, MineList može slati glasove tvom serveru putem NuVotifiera. Podržane su obje verzije protokola. Verzija 1 koristi javni RSA ključ, verzija 2 koristi token.

Instaliraj NuVotifier na svoj server i ponovno ga pokreni.
U panelu za vlasnike upiši host, port (zadano 8192) i javni ključ (v1) ili token (v2).
Pritisni Pošalji probni glas i provjeri bilježi li tvoj server glas.

Ako test ne uspije, provjeri je li Votifier port otvoren u tvom firewallu i je li ključ kopiran bez razmaka i prijeloma redaka.

Live banner

Svaki server ima live banner veličine 468x60 piksela koji prikazuje trenutačni status i broj igrača:

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

Primjer ugradnje u HTML:

<a href="https://minelist.eu/hr/server/tvoj-slug">
  <img src="https://minelist.eu/banner/tvoj-slug.png" width="468" height="60" alt="Glasaj za nas na MineListu">
</a>

Dobre prakse

Spremi javnu statistiku u predmemoriju (cache) najmanje minutu umjesto da pozivaš API pri svakom prikazu stranice.
Nikad ne stavljaj API ključ u kod na strani klijenta ni u javni repozitorij.
Endpoint za preuzimanje koristi samo jednom za svaku nagradu.