API ψήφων

Βασικά

• Οι απαντήσεις είναι σε JSON. Στείλε την κεφαλίδα Accept: application/json με κάθε αίτημα.
• Δεν απαιτείται αυθεντικοποίηση.
• Όριο: 30 αιτήματα το λεπτό ανά διεύθυνση IP.
• Όλες οι ώρες είναι σε UTC.
• Ένας παίκτης μπορεί να ψηφίσει έναν server μία φορά την ημέρα, και ένας server μπορεί να πάρει το πολύ 30 ψήφους την ημέρα.

Το UUID του server σου

Κάθε server της λίστας έχει ένα μόνιμο UUID που τον αναγνωρίζει στο API, οπότε η σύνδεση συνεχίζει να λειτουργεί ακόμα κι αν αλλάξει η διεύθυνση του server. Οι ιδιοκτήτες βλέπουν το UUID στη σελίδα του server. Αν δεν μπορείς να το βρεις, επικοινώνησε μαζί μας με τη διεύθυνση του server σου και θα σου το στείλουμε.

Λίστα ψήφων

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

Επιστρέφει τις ψήφους του server, με τις πιο πρόσφατες πρώτες. Οι ανώνυμες ψήφοι (χωρίς ψευδώνυμο) δεν περιλαμβάνονται.

Παράμετροι ερωτήματος

Όλες οι παράμετροι είναι προαιρετικές.

Παράδειγμα αιτήματος

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

Παράδειγμα απάντησης

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

Χρησιμοποίησε το links.next ή την παράμετρο page για να φέρεις τις επόμενες σελίδες. Το αντικείμενο meta περιέχει επίσης τα τυπικά πεδία σελιδοποίησης path και links.

Σφάλματα

• 404: δεν υπάρχει server με αυτό το UUID. Έλεγξε ότι αντέγραψες ολόκληρο το UUID.
• 422: μια παράμετρος δεν είναι έγκυρη, για παράδειγμα limit=500. Το αντικείμενο errors της απάντησης αναφέρει ποια παράμετρος φταίει και τι ακριβώς είναι λάθος.
• 429: περισσότερα από 30 αιτήματα μέσα σε ένα λεπτό. Περίμενε όσο χρόνο δείχνει η κεφαλίδα Retry-After.

Ανταμοιβές για ψήφους μέσα από plugin

Ο πιο απλός τρόπος: όταν ένας παίκτης τρέχει μια εντολή όπως /vote claim, ρώτα το API αν αυτό το ψευδώνυμο ψήφισε σήμερα και δώσε την ανταμοιβή αν ψήφισε και δεν την έχει ήδη πάρει. Αποθήκευε την ημερομηνία παραλαβής για κάθε παίκτη, ώστε μια ψήφος να μην εξαργυρώνεται δύο φορές.

Ένας ελάχιστος έλεγχος για plugin Paper ή Spigot (Java 11+), που τρέχει εκτός του main thread:

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

Όρισε το API_URL σε https://mcserverscout.com/api/servers/{uuid}/votes με το UUID του server σου. Δώσε την ανταμοιβή πίσω στο main thread, για παράδειγμα με Bukkit.getScheduler().runTask(...). Αν προτιμάς να επιβραβεύεις τους παίκτες αυτόματα, κάνε ερώτημα στο API κάθε λίγα λεπτά με το date_from ορισμένο στη σημερινή ημερομηνία και επεξεργάσου τα ψευδώνυμα που δεν έχεις δει ακόμα. Μείνε με άνεση κάτω από το όριο των 30 αιτημάτων το λεπτό.