Äänestys-API

Perusteet

• Vastaukset ovat JSON-muodossa. Lähetä jokaisen pyynnön mukana otsake Accept: application/json.
• Tunnistautumista ei tarvita.
• Raja: 30 pyyntöä minuutissa IP-osoitetta kohden.
• Kaikki ajat ovat UTC-aikaa.
• Pelaaja voi äänestää palvelinta kerran päivässä, ja palvelin voi saada enintään 30 ääntä päivässä.

Palvelimesi UUID

Jokaisella listatulla palvelimella on pysyvä UUID, joka tunnistaa sen API:ssa, joten integraatio toimii, vaikka palvelimen osoite muuttuisi. UUID näytetään omistajille palvelinsivulla. Jos et löydä sitä, ota meihin yhteyttä ja kerro palvelimesi osoite, niin lähetämme sen sinulle.

Äänten listaus

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

Palauttaa palvelimen äänet uusimmasta alkaen. Nimettömiä ääniä (ilman nimimerkkiä) ei sisällytetä.

Kyselyparametrit

Kaikki parametrit ovat valinnaisia.

Esimerkkipyyntö

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

Esimerkkivastaus

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

Hae seuraavat sivut kentän links.next tai parametrin page avulla. meta-objekti sisältää myös sivutuksen vakiokentät path ja links.

Virheet

• 404: tällä UUID:llä ei löydy palvelinta. Tarkista, että kopioit koko UUID:n.
• 422: jokin parametri on virheellinen, esimerkiksi limit=500. Vastauksen errors-objekti kertoo, mikä parametri on kyseessä ja mikä siinä on vialla.
• 429: yli 30 pyyntöä minuutissa. Odota otsakkeessa Retry-After ilmoitettu aika.

Äänien palkitseminen pluginissa

Yksinkertaisin tapa: kun pelaaja suorittaa komennon, kuten /vote claim, kysy API:lta, onko kyseinen nimimerkki äänestänyt tänään, ja anna palkinto, jos on eikä palkintoa ole vielä lunastettu. Tallenna lunastuspäivä pelaajakohtaisesti, jotta samaa ääntä ei voi lunastaa kahdesti.

Minimaalinen tarkistus Paper- tai Spigot-pluginille (Java 11+), joka ajetaan pääsäikeen ulkopuolella:

// 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\":[]"));
}

Aseta API_URL-arvoksi https://mcserverscout.com/api/servers/{uuid}/votes palvelimesi UUID:llä. Anna palkinto takaisin pääsäikeessä, esimerkiksi kutsulla Bukkit.getScheduler().runTask(...). Jos haluat palkita pelaajat automaattisesti, kysele API:lta muutaman minuutin välein niin, että date_from on tämä päivä, ja käsittele nimimerkit, joita et ole vielä nähnyt. Pysy selvästi alle 30 pyynnön minuuttirajan.