Röst-API

Grunderna

• Svaren är i JSON. Skicka headern Accept: application/json med varje förfrågan.
• Ingen autentisering krävs.
• Gräns: 30 förfrågningar per minut och IP-adress.
• Alla tider anges i UTC.
• En spelare kan rösta på en server en gång per dag, och en server kan få högst 30 röster per dag.

Din servers UUID

Varje listad server har ett permanent UUID som identifierar den i API:t, så att det fortsätter fungera även om serverns adress ändras. UUID:t visas för ägare på serversidan. Om du inte hittar det, kontakta oss med din serveradress så skickar vi det till dig.

Lista röster

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

Returnerar rösterna på servern, nyaste först. Anonyma röster (utan användarnamn) ingår inte.

Frågeparametrar

Alla parametrar är valfria.

Exempel på förfrågan

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

Exempel 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
  }
}

Använd links.next eller parametern page för att hämta fler sidor. Objektet meta innehåller även de vanliga pagineringsfälten path och links.

Fel

• 404: det finns ingen server med det här UUID:t. Kontrollera att du kopierade hela UUID:t.
• 422: en parameter är ogiltig, till exempel limit=500. Objektet errors i svaret anger parametern och vad som är fel med den.
• 429: fler än 30 förfrågningar på en minut. Vänta den tid som anges i headern Retry-After.

Belöna röster i ett plugin

Det enklaste sättet: när en spelare kör ett kommando som /vote claim, fråga API:t om det användarnamnet har röstat idag, och ge belöningen om det har gjort det och belöningen inte redan har hämtats ut. Spara datumet för uthämtningen per spelare så att en röst inte kan lösas in två gånger.

En minimal kontroll för ett Paper- eller Spigot-plugin (Java 11+), som körs utanför huvudtrå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\":[]"));
}

Sätt API_URL till https://mcserverscout.com/api/servers/{uuid}/votes med din servers UUID. Dela ut belöningen på huvudtråden, till exempel med Bukkit.getScheduler().runTask(...). Om du hellre vill belöna spelare automatiskt kan du fråga API:t med några minuters mellanrum med date_from satt till dagens datum och behandla användarnamn som du inte har sett tidigare. Håll dig gott och väl under gränsen på 30 förfrågningar per minut.