API de vote

Les bases

• Les réponses sont au format JSON. Envoyez l’en-tête Accept: application/json avec chaque requête.
• Aucune authentification n’est requise.
• Limite : 30 requêtes par minute et par adresse IP.
• Toutes les heures sont en UTC.
• Un joueur peut voter pour un serveur une fois par jour, et un serveur peut recevoir au maximum 30 votes par jour.

L’UUID de votre serveur

Chaque serveur listé possède un UUID permanent qui l’identifie dans l’API : il continue donc de fonctionner même si l’adresse du serveur change. L’UUID est affiché aux propriétaires sur la page du serveur. Si vous ne le trouvez pas, contactez-nous en indiquant l’adresse de votre serveur et nous vous l’enverrons.

Lister les votes

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

Renvoie les votes du serveur, du plus récent au plus ancien. Les votes anonymes (sans pseudo) ne sont pas inclus.

Paramètres de requête

Tous les paramètres sont facultatifs.

Exemple de requête

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

Exemple de réponse

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

Utilisez links.next ou le paramètre page pour récupérer les pages suivantes. L’objet meta contient aussi les champs de pagination standard path et links.

Erreurs

• 404: aucun serveur avec cet UUID. Vérifiez que vous avez copié l’UUID en entier.
• 422: un paramètre n’est pas valide, par exemple limit=500. L’objet errors de la réponse indique le paramètre concerné et le problème.
• 429: plus de 30 requêtes en une minute. Attendez le délai indiqué dans l’en-tête Retry-After.

Récompenser les votes dans un plugin

L’approche la plus simple : quand un joueur exécute une commande comme /vote claim, demandez à l’API si ce pseudo a voté aujourd’hui, et donnez la récompense si c’est le cas et qu’elle n’a pas encore été réclamée. Enregistrez la date de réclamation pour chaque joueur, afin qu’un vote ne puisse pas être utilisé deux fois.

Une vérification minimale pour un plugin Paper ou Spigot (Java 11+), exécutée hors du thread principal :

// Renvoie true si le joueur a voté aujourd’hui (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\":[]"));
}

Définissez API_URL sur https://mcserverscout.com/api/servers/{uuid}/votes avec l’UUID de votre serveur. Donnez la récompense sur le thread principal, par exemple avec Bukkit.getScheduler().runTask(...). Si vous préférez récompenser les joueurs automatiquement, interrogez l’API toutes les quelques minutes avec date_from fixé à aujourd’hui et traitez les pseudos que vous n’avez pas encore vus. Restez bien en dessous de la limite de 30 requêtes par minute.