API hlasování pro Minecraft servery

Základy

Odpovědi jsou ve formátu JSON. S každým požadavkem posílej hlavičku Accept: application/json.
Není potřeba žádné ověření.
Limit: 30 požadavků za minutu na IP adresu.
Všechny časy jsou v UTC.
Hráč může pro server hlasovat jednou denně a server může dostat nejvýše 30 hlasů denně.

UUID tvého serveru

Každý server na seznamu má trvalé UUID, které ho v API identifikuje, takže vše funguje dál, i když se adresa serveru změní. UUID se majitelům zobrazuje na stránce serveru. Pokud ho nemůžeš najít, napiš nám adresu svého serveru a UUID ti pošleme.

Seznam hlasů

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

Vrací hlasy pro server, od nejnovějších. Anonymní hlasy (bez přezdívky) nejsou zahrnuty.

Parametry dotazu

Všechny parametry jsou nepovinné.

Parametr	Typ	Popis
nick	string	Jen hlasy od přesně této přezdívky (rozlišuje velká a malá písmena, 2–128 znaků).
date_from	date	Hlasy odevzdané v tento den nebo později, YYYY-MM-DD.
date_to	date	Hlasy odevzdané nejpozději do konce tohoto dne, YYYY-MM-DD.
limit	integer	Počet výsledků na stránku, 1–200. Výchozí 100.
page	integer	Číslo stránky, 1–100.

Ukázkový požadavek

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

Ukázková odpověď

{
  "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
  }
}

Další stránky načteš přes links.next nebo parametr page. Objekt meta obsahuje také standardní stránkovací pole path a links.

Chyby

404: server s tímto UUID neexistuje. Zkontroluj, že jsi zkopíroval celé UUID.
422: některý parametr je neplatný, například limit=500. Objekt errors v odpovědi uvádí, o který parametr jde a co je na něm špatně.
429: více než 30 požadavků za minutu. Počkej dobu uvedenou v hlavičce Retry-After.

Odměny za hlasy v pluginu

Nejjednodušší postup: když hráč použije příkaz jako /vote claim, zeptej se API, jestli tato přezdívka dnes hlasovala, a pokud ano a odměna ještě nebyla vyzvednuta, dej ji hráči. Ukládej si u každého hráče datum vyzvednutí, aby nešlo jeden hlas uplatnit dvakrát.

Minimální kontrola pro plugin pro Paper nebo Spigot (Java 11+), spouštěná mimo hlavní vlákno:

// Returns true if the player has voted today (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\":[]"));
}

Nastav API_URL na https://mcserverscout.com/api/servers/{uuid}/votes s UUID tvého serveru. Odměnu pak předej zpět v hlavním vlákně, například přes Bukkit.getScheduler().runTask(...). Pokud chceš hráče odměňovat automaticky, dotazuj se API každých pár minut s date_from nastaveným na dnešek a zpracuj přezdívky, které jsi ještě neviděl. Drž se hluboko pod limitem 30 požadavků za minutu.