API dei voti

Nozioni di base

• Le risposte sono in JSON. Invia l'header Accept: application/json con ogni richiesta.
• Non è richiesta alcuna autenticazione.
• Limite: 30 richieste al minuto per indirizzo IP.
• Tutti gli orari sono in UTC.
• Un giocatore può votare un server una volta al giorno, e un server può ricevere al massimo 30 voti al giorno.

L'UUID del tuo server

Ogni server in lista ha un UUID permanente che lo identifica nell'API, quindi continua a funzionare anche se l'indirizzo del server cambia. L'UUID viene mostrato ai proprietari sulla pagina del server. Se non riesci a trovarlo, contattaci indicando l'indirizzo del tuo server e te lo invieremo.

Elenco dei voti

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

Restituisce i voti del server, dai più recenti. I voti anonimi (senza nickname) non sono inclusi.

Parametri della query

Tutti i parametri sono facoltativi.

Esempio di richiesta

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

Esempio di risposta

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

Usa links.next o il parametro page per recuperare le pagine successive. L'oggetto meta contiene anche i campi di paginazione standard path e links.

Errori

• 404: nessun server con questo UUID. Controlla di aver copiato l'UUID per intero.
• 422: un parametro non è valido, ad esempio limit=500. L'oggetto errors della risposta indica il parametro e cosa c'è che non va.
• 429: più di 30 richieste in un minuto. Attendi il tempo indicato nell'header Retry-After.

Premiare i voti con un plugin

L'approccio più semplice: quando un giocatore esegue un comando come /vote claim, chiedi all'API se quel nickname ha votato oggi e consegna la ricompensa se ha votato e non l'ha ancora riscattata. Salva la data di riscatto per ogni giocatore, così un voto non può essere riscattato due volte.

Un controllo minimo per un plugin Paper o Spigot (Java 11+), da eseguire fuori dal thread principale:

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

Imposta API_URL su https://mcserverscout.com/api/servers/{uuid}/votes con l'UUID del tuo server. Consegna la ricompensa di nuovo sul thread principale, ad esempio con Bukkit.getScheduler().runTask(...). Se preferisci premiare i giocatori in automatico, interroga l'API ogni pochi minuti con date_from impostato sulla data di oggi ed elabora i nickname che non hai ancora visto. Resta ben al di sotto del limite di 30 richieste al minuto.