MineList API serverių savininkams

MineList API leidžia tavo serveriui patikrinti, ar žaidėjas pabalsavo, išduoti prizą tiksliai vieną kartą ir skaityti viešą statistiką. Visi galiniai taškai grąžina JSON ir naudoja paprastas HTTPS GET užklausas, todėl veikia iš bet kurios kalbos.

Kaip gauti API raktą

Pridėk savo serverį, perimk jį ir atidaryk savininko skydelį. API raktas rodomas serverio nustatymų puslapyje. Laikyk jį paslaptyje, nes jis identifikuoja tavo serverį. Jei raktas nutekėjo, sugeneruok naują skydelyje ir atnaujink savo papildinį ar skriptą.

Visų galinių taškų bazinis adresas yra https://minelist.eu.

Balso patikra

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

Parodo, ar žaidėjas šiandien pabalsavo ir ar prizas jau atsiimtas.

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

voted yra true, jei slapyvardis turi balsą už tavo serverį dabartinę UTC dieną.
claimed yra true, jei tą balsą jau pažymėjai kaip atsiimtą.
next_vote_utc yra laikas, kada žaidėjas vėl gali balsuoti.

Balso atsiėmimas

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

Pažymi šiandienos balsą kaip atsiimtą. Iškviesk jį prieš pat išduodamas prizą, kad žaidėjas negalėtų atsiimti dukart. Galimi atsakymai:

Atsakymas	Reikšmė
`{"voted":true,"claimed":true}`	Balsas galiojo ir dabar atsiimtas. Išduok prizą.
`{"voted":true,"claimed":false,"already_claimed":true}`	Balsas jau buvo atsiimtas anksčiau. Neduok nieko.
`{"voted":false,"claimed":false}`	Žaidėjas šiandien nebalsavo.

Šio mėnesio balsų sąrašas

GET /api/v1/votes?key=API_KEY

Grąžina visus balsus, kuriuos tavo serveris gavo dabartinį mėnesį. Tai naudinga mėnesio geriausių balsuotojų prizams ir lyderių lentelėms tavo svetainėje.

Vieša serverio statistika

GET /api/v1/server/<slug>

Šiam galiniam taškui raktas nereikalingas. Slug yra paskutinė serverio adreso dalis MineList. Atsakymo laukų pavyzdys:

Laukas	Aprašymas
`name`	Serverio pavadinimas
`url`	Serverio svetainė
`ip`	Prisijungimo adresas
`online`	Ar paskutinė patikra pavyko
`players`	Žaidėjai online paskutinės patikros metu
`max_players`	Žaidėjų vietos
`version`	Serverio versija
`votes_month`	Šio mėnesio balsai
`votes_total`	Balsai nuo serverio pridėjimo
`uptime_30`	Veikimo laikas per paskutines 30 dienų procentais
`rating`	Vidutinis įvertinimas
`last_check`	Paskutinės patikros laikas

Pavyzdys su curl

Tai visa logika komandinėje eilutėje. Bet kuri kalba, galinti siųsti HTTP užklausą, pavyzdžiui Java, PHP, Python ar Node.js, daro tą patį.

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

Išanalizuok JSON, o jei claimed yra true, vykdyk prizo komandą, pavyzdžiui give Steve diamond 3.

NuVotifier palaikymas

Jei nori prizų iš karto, be nuolatinio klausinėjimo, MineList gali siųsti balsus į tavo serverį per NuVotifier. Palaikomos abi protokolo versijos. 1 versija naudoja RSA viešąjį raktą, 2 versija naudoja žetoną (token).

Įdiek NuVotifier savo serveryje ir perkrauk jį.
Savininko skydelyje įrašyk host adresą, prievadą (pagal nutylėjimą 8192) ir viešąjį raktą (v1) arba žetoną (v2).
Paspausk Siųsti bandomąjį balsą ir patikrink, ar serveris užfiksuoja balsą žurnale.

Jei bandymas nepavyksta, įsitikink, kad Votifier prievadas atidarytas ugniasienėje ir kad raktas nukopijuotas be tarpų ar eilučių lūžių.

Gyvas banneris

Kiekvienas serveris turi 468x60 pikselių gyvą banerį, rodantį dabartinę būseną ir žaidėjų skaičių:

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

HTML įterpimo pavyzdys:

<a href="https://minelist.eu/lt/server/tavo-slug">
  <img src="https://minelist.eu/banner/tavo-slug.png" width="468" height="60" alt="Balsuok už mus MineList">
</a>

Gera praktika

Laikyk viešą statistiką talpykloje bent minutę, užuot kreipęsis į API kiekvieną kartą atidarius puslapį.
Niekada nedėk API rakto į kliento pusės kodą ar viešą saugyklą.
Atsiėmimo galinį tašką naudok tik vieną kartą už prizą.