API MineList pozwala twojemu serwerowi sprawdzić, czy gracz zagłosował, przyznać nagrodę dokładnie raz i pobrać publiczne statystyki. Wszystkie endpointy zwracają JSON i korzystają ze zwykłych żądań HTTPS GET, więc działają z każdego języka programowania.
Jak zdobyć klucz API
Dodaj swój serwer, przejmij go i otwórz panel właściciela. Klucz API znajdziesz na stronie ustawień serwera. Trzymaj go w tajemnicy, bo identyfikuje twój serwer. Jeśli wycieknie, wygeneruj w panelu nowy i zaktualizuj wtyczkę lub skrypt.
Podstawowy adres wszystkich endpointów to https://minelist.eu.
Sprawdzanie głosu
GET /api/v1/vote?key=API_KEY&username=NICKPokazuje, czy gracz zagłosował dzisiaj i czy nagroda została już odebrana.
{"voted":true,"claimed":false,"next_vote_utc":"2026-10-31T00:00:00Z"}votedma wartość true, jeśli nick oddał głos na twój serwer w bieżącym dniu UTC.claimedma wartość true, jeśli ten głos został już przez ciebie oznaczony jako odebrany.next_vote_utcto czas, kiedy gracz może zagłosować ponownie.
Odbieranie głosu
GET /api/v1/vote/claim?key=API_KEY&username=NICKOznacza dzisiejszy głos jako odebrany. Wywołaj go tuż przed przyznaniem nagrody, aby gracz nie mógł odebrać jej dwa razy. Możliwe odpowiedzi:
| Odpowiedź | Znaczenie |
|---|---|
{"voted":true,"claimed":true} | Głos był ważny i jest teraz odebrany. Przyznaj nagrodę. |
{"voted":true,"claimed":false,"already_claimed":true} | Głos został odebrany już wcześniej. Nie przyznawaj niczego. |
{"voted":false,"claimed":false} | Gracz nie głosował dzisiaj. |
Lista głosów z tego miesiąca
GET /api/v1/votes?key=API_KEYZwraca wszystkie głosy, które twój serwer otrzymał w bieżącym miesiącu. Przydaje się do miesięcznych nagród dla najlepiej głosujących i rankingów na twojej stronie.
Publiczne statystyki serwera
GET /api/v1/server/<slug>Ten endpoint nie wymaga klucza. Slug to ostatnia część adresu serwera w MineList. Pola odpowiedzi:
| Pole | Opis |
|---|---|
name | Nazwa serwera |
url | Strona serwera |
ip | Adres połączenia |
online | Czy ostatnie sprawdzenie się powiodło |
players | Liczba graczy online przy ostatnim sprawdzeniu |
max_players | Liczba miejsc dla graczy |
version | Wersja serwera |
votes_month | Głosy w tym miesiącu |
votes_total | Głosy od dodania serwera |
uptime_30 | Dostępność w ostatnich 30 dniach w procentach |
rating | Średnia ocena |
last_check | Czas ostatniego sprawdzenia |
Przykład z curl
Tak wygląda cała logika w powłoce. To samo zrobi każdy język, który potrafi wysłać żądanie HTTP, na przykład Java, PHP, Python lub Node.js.
curl -s "https://minelist.eu/api/v1/vote/claim?key=API_KEY&username=Steve"Przetwórz JSON, a jeśli claimed ma wartość true, uruchom komendę z nagrodą, na przykład give Steve diamond 3.
Obsługa NuVotifier
Jeśli wolisz nagrody natychmiast i bez odpytywania, MineList może wysyłać głosy na twój serwer przez NuVotifier. Obsługujemy obie wersje protokołu. Wersja 1 używa klucza publicznego RSA, wersja 2 tokenu.
- Zainstaluj NuVotifier na serwerze i uruchom go ponownie.
- W panelu właściciela wpisz host, port (domyślnie 8192) oraz klucz publiczny (v1) lub token (v2).
- Kliknij Wyślij testowy głos i sprawdź, czy serwer zapisuje go w logach.
Jeśli test się nie powiedzie, upewnij się, że port Votifiera jest otwarty w zaporze sieciowej, a klucz został skopiowany bez spacji i łamań wiersza.
Baner na żywo
Każdy serwer ma baner na żywo o wymiarach 468x60 pikseli, który pokazuje aktualny status i liczbę graczy:
https://minelist.eu/banner/<slug>.pngPrzykład osadzenia w HTML:
<a href="https://minelist.eu/pl/server/twoj-slug">
<img src="https://minelist.eu/banner/twoj-slug.png" width="468" height="60" alt="Zagłosuj na nas w MineList">
</a>Dobre praktyki
- Zapisuj publiczne statystyki w pamięci podręcznej (cache) na co najmniej minutę, zamiast wywoływać API przy każdym wyświetleniu strony.
- Nigdy nie umieszczaj klucza API w kodzie po stronie klienta ani w publicznym repozytorium.
- Endpoint odbierania wywołuj tylko raz na jedną nagrodę.