API głosów

Podstawy

• Odpowiedzi są w formacie JSON. Do każdego zapytania dołącz nagłówek Accept: application/json.
• Uwierzytelnianie nie jest wymagane.
• Limit: 30 zapytań na minutę z jednego adresu IP.
• Wszystkie daty i godziny są w strefie UTC.
• Gracz może zagłosować na serwer raz dziennie, a serwer może dostać maksymalnie 30 głosów na dobę.

UUID serwera

Każdy serwer na liście ma stały identyfikator UUID, którym posługuje się API — dzięki temu integracja działa dalej nawet po zmianie adresu serwera. UUID jest widoczny dla właścicieli na stronie serwera. Jeśli nie możesz go znaleźć, napisz do nas, podając adres serwera, a prześlemy Ci go.

Lista głosów

GET https://mcserverscout.com/api/servers/{uuid}/votes

Zwraca głosy oddane na serwer, od najnowszych. Głosy anonimowe (bez nicku) nie są uwzględniane.

Parametry zapytania

Wszystkie parametry są opcjonalne.

Przykładowe zapytanie

curl -H "Accept: application/json" \
  "https://mcserverscout.com/api/servers/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/votes?nick=Steve&date_from=2026-10-23"

Przykładowa odpowiedź

{
  "data": [
    {
      "nick": "Steve",
      "created_at": "2026-10-23T14:30:00+00:00"
    }
  ],
  "links": {
    "first": "https://mcserverscout.com/api/servers/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/votes?page=1",
    "last": "https://mcserverscout.com/api/servers/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/votes?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 100,
    "to": 1,
    "total": 1
  }
}

Kolejne strony pobierzesz przez links.next albo parametr page. Obiekt meta zawiera też standardowe pola paginacji path i links.

Błędy

• 404: nie ma serwera o takim UUID. Sprawdź, czy identyfikator został skopiowany w całości.
• 422: niepoprawny parametr, np. limit=500. Obiekt errors w odpowiedzi wskazuje parametr i opisuje, co jest nie tak.
• 429: ponad 30 zapytań w ciągu minuty. Odczekaj czas podany w nagłówku Retry-After.

Nagrody za głosy w pluginie

Najprostszy sposób: gdy gracz wpisze komendę, np. /vote odbierz, zapytaj API, czy ten nick zagłosował dzisiaj, i daj nagrodę, jeśli tak i jeśli nie została jeszcze odebrana. Zapisuj datę odbioru dla każdego gracza, żeby jednego głosu nie dało się wykorzystać dwa razy.

Minimalne sprawdzenie dla pluginu Paper lub Spigot (Java 11+), uruchamiane poza głównym wątkiem:

// Zwraca true, jeśli gracz zagłosował dzisiaj (UTC).
CompletableFuture<Boolean> hasVotedToday(String nick) {
    String today = LocalDate.now(ZoneOffset.UTC).toString();
    URI uri = URI.create(API_URL
        + "?limit=1&date_from=" + today
        + "&nick=" + URLEncoder.encode(nick, StandardCharsets.UTF_8));

    HttpRequest request = HttpRequest.newBuilder(uri)
        .header("Accept", "application/json")
        .build();

    return HttpClient.newHttpClient()
        .sendAsync(request, HttpResponse.BodyHandlers.ofString())
        .thenApply(response -> response.statusCode() == 200
            && !response.body().contains("\"data\":[]"));
}

Ustaw API_URL na https://mcserverscout.com/api/servers/{uuid}/votes z UUID swojego serwera. Nagrodę przyznaj z powrotem w głównym wątku, np. przez Bukkit.getScheduler().runTask(...). Jeśli wolisz nagradzać automatycznie, odpytuj API co kilka minut z date_from ustawionym na dzisiejszą datę i obsługuj tylko nowe nicki. Trzymaj się z dala od limitu 30 zapytań na minutę.