Vote-API

Grundlagen

• Antworten kommen als JSON. Sende bei jeder Anfrage den Header Accept: application/json mit.
• Eine Authentifizierung ist nicht erforderlich.
• Limit: 30 Anfragen pro Minute und IP-Adresse.
• Alle Zeiten sind in UTC.
• Ein Spieler kann einmal am Tag für einen Server abstimmen, und ein Server kann höchstens 30 Stimmen pro Tag erhalten.

Die UUID deines Servers

Jeder gelistete Server hat eine dauerhafte UUID, die ihn in der API identifiziert – sie funktioniert also weiter, auch wenn sich die Adresse des Servers ändert. Betreibern wird die UUID auf der Serverseite angezeigt. Wenn du sie nicht findest, kontaktiere uns mit deiner Serveradresse, und wir schicken sie dir.

Stimmen abrufen

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

Liefert die Stimmen für den Server, die neuesten zuerst. Anonyme Stimmen (ohne Nickname) sind nicht enthalten.

Query-Parameter

Alle Parameter sind optional.

Beispielanfrage

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

Beispielantwort

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

Nutze links.next oder den Parameter page, um weitere Seiten abzurufen. Das Objekt meta enthält außerdem die üblichen Paginierungsfelder path und links.

Fehler

• 404: Es gibt keinen Server mit dieser UUID. Prüfe, ob du die ganze UUID kopiert hast.
• 422: Ein Parameter ist ungültig, zum Beispiel limit=500. Das Objekt errors in der Antwort nennt den Parameter und was daran falsch ist.
• 429: mehr als 30 Anfragen in einer Minute. Warte die im Header Retry-After angegebene Zeit ab.

Stimmen in einem Plugin belohnen

Der einfachste Ansatz: Wenn ein Spieler einen Befehl wie /vote claim ausführt, frag die API, ob dieser Nickname heute abgestimmt hat, und gib die Belohnung aus, falls ja und sie noch nicht abgeholt wurde. Speichere das Abholdatum pro Spieler, damit eine Stimme nicht doppelt eingelöst werden kann.

Eine minimale Prüfung für ein Paper- oder Spigot-Plugin (Java 11+), ausgeführt außerhalb des Main-Threads:

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

Setze API_URL auf https://mcserverscout.com/api/servers/{uuid}/votes mit der UUID deines Servers. Gib die Belohnung wieder auf dem Main-Thread aus, zum Beispiel mit Bukkit.getScheduler().runTask(...). Wenn du Spieler lieber automatisch belohnen willst, frag die API alle paar Minuten mit date_from auf das heutige Datum ab und verarbeite Nicknames, die du noch nicht gesehen hast. Bleib dabei deutlich unter dem Limit von 30 Anfragen pro Minute.