API голосування

Основи

• Відповіді надходять у форматі JSON. Надсилайте заголовок Accept: application/json з кожним запитом.
• Автентифікація не потрібна.
• Ліміт: 30 запитів на хвилину з однієї IP-адреси.
• Увесь час указано в UTC.
• Гравець може голосувати за сервер раз на день, а сервер може отримати не більше 30 голосів на день.

UUID вашого сервера

Кожен сервер у списку має постійний UUID, який ідентифікує його в API, тож усе працюватиме, навіть якщо адреса сервера зміниться. Власникам UUID показується на сторінці сервера. Якщо не можете його знайти, напишіть нам, указавши адресу сервера, і ми його надішлемо.

Список голосів

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

Повертає голоси за сервер, від найновіших. Анонімні голоси (без ніка) не включаються.

Параметри запиту

Усі параметри необов’язкові.

Приклад запиту

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: сервера з таким UUID немає. Перевірте, чи ви скопіювали UUID повністю.
• 422: недійсний параметр, наприклад limit=500. Об’єкт errors у відповіді вказує параметр і що з ним не так.
• 429: понад 30 запитів за хвилину. Зачекайте стільки, скільки вказано в заголовку Retry-After.

Нагороди за голоси в плагіні

Найпростіший підхід: коли гравець виконує команду на кшталт /vote claim, запитайте в API, чи голосував цей нік сьогодні, і видайте нагороду, якщо голос є і його ще не забрали. Зберігайте дату отримання нагороди для кожного гравця, щоб один голос не можна було використати двічі.

Мінімальна перевірка для плагіна Paper або Spigot (Java 11+), яку слід виконувати поза головним потоком:

// 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 вашого сервера. Нагороду видавайте вже в головному потоці, наприклад через Bukkit.getScheduler().runTask(...). Якщо хочете нагороджувати гравців автоматично, опитуйте API кожні кілька хвилин із date_from, установленим на сьогоднішню дату, і обробляйте ніки, яких ще не бачили. Тримайтеся значно нижче ліміту 30 запитів на хвилину.