Stemme-API

Grunnleggende

• Svarene er i JSON. Send headeren Accept: application/json med hver forespørsel.
• Ingen autentisering kreves.
• Grense: 30 forespørsler per minutt per IP-adresse.
• Alle tidspunkter er i UTC.
• En spiller kan stemme på en server én gang om dagen, og en server kan få maks 30 stemmer per dag.

Serverens UUID

Hver oppført server har en permanent UUID som identifiserer den i API-et, så det fortsetter å fungere selv om serverens adresse endres. UUID-en vises for eiere på serversiden. Finner du den ikke, kan du kontakte oss med serveradressen din, så sender vi den til deg.

Hent stemmer

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

Returnerer stemmene for serveren, nyeste først. Anonyme stemmer (uten kallenavn) er ikke med.

Spørringsparametere

Alle parametere er valgfrie.

Eksempel på forespørsel

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

Eksempel på svar

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

Bruk links.next eller parameteren page for å hente flere sider. Objektet meta inneholder også standardfeltene for paginering, path og links.

Feil

• 404: ingen server med denne UUID-en. Sjekk at du kopierte hele UUID-en.
• 422: en parameter er ugyldig, for eksempel limit=500. Objektet errors i svaret oppgir parameteren og hva som er galt med den.
• 429: mer enn 30 forespørsler i løpet av et minutt. Vent så lenge som headeren Retry-After oppgir.

Belønne stemmer i en plugin

Den enkleste fremgangsmåten: når en spiller kjører en kommando som /vote claim, spør du API-et om det kallenavnet har stemt i dag, og gir belønningen hvis det har det og den ikke allerede er hentet. Lagre datoen belønningen ble hentet per spiller, så en stemme ikke kan løses inn to ganger.

En minimal sjekk for en Paper- eller Spigot-plugin (Java 11+), kjørt utenfor hovedtråden:

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

Sett API_URL til https://mcserverscout.com/api/servers/{uuid}/votes med serverens UUID. Del ut belønningen tilbake på hovedtråden, for eksempel med Bukkit.getScheduler().runTask(...). Vil du heller belønne spillere automatisk, kan du spørre API-et med noen minutters mellomrom med date_from satt til dagens dato og behandle kallenavn du ikke har sett før. Hold deg godt under grensen på 30 forespørsler per minutt.