API dokumentace

Server

Pokud se nenajde server podle slug tak vrátíme 404.

GET https://www.minecraft-list.cz/api/server/{slug}

200 Získá základní informace o serveru

                        {
    "name": "Minecraft server name",
    "rank": 2,
    "slug": "minecraft-server-name",
    "votes": 455,
    "rating": 4.95,
    "reviews_count": 4,
    "uptime": 99.99,
    "online_players": 92,
    "max_players": 100
}

GET https://www.minecraft-list.cz/api/votes/{slug}

200 Získá počet aktivních hlasů a jejich kompletní seznam.

                        {
    "votes_count": 543,
    "votes": [
        {
            "created_at": "2021-11-30 20:20:20",
            "delivered_at": "2021-11-30 20:20:27",
            "username": "Kogol"
        },
        {
            "created_at": "..."
        }
    ]
}

GET https://www.minecraft-list.cz/api/reviews/{slug}

200 Získá počet recenzí a jejich kompletní seznam.

                        {
    "reviews_count": 9,
    "server_rating": 4.95,
    "reviews": [
        {
            "created_at": "2021-11-30 20:20:20",
            "updated_at": "2021-11-30 20:22:20",
            "username": "Kolega",
            "review": "Tento server celkem ujde.",
            "rating": 3,
            "upvotes": -32,
            "votes_count": 128,
            "server_reply": "Dekujeme za tvou recenzi ale plne nesouhlasime. -Kogol"
        },
        [
            "..."
        ]
    ]
}

GET https://www.minecraft-list.cz/api/top-voters/{slug}

200 Vrátí seznam 20 top aktivních hlasujích seřazený podle hlasů.

                        [
    {
        "username": "Kogol",
        "votes": 129
    },
    {
        "username": "Dragan",
        "votes": 128
    },
    {
        "username": "..."
    }
]

GET https://www.minecraft-list.cz/api/votes/{slug}/{month}/{year}

200 Vrátí všechny hlasy v daném měsíci. (měsíc a rok musí být číslo)

                        {
    "votes": [
        {
            "created_at": "2022-01-04 17:11:35",
            "delivered_at": "2022-01-04 17:31:35",
            "username": "Dragan"
        },
        {
            "created_at": "2022-01-04 17:21:32",
            "delivered_at": "2022-01-05 16:11:35",
            "username": "Kogol"
        },
        {
            "created_at": "..."
        }
    ],
    "votes_count": 5678
}

Server + hráč

GET https://www.minecraft-list.cz/api/server/{slug}/player/{player}

200 Údaje o aktivních hlasech hráče na daném serveru.

                        {
    "votes": [
        {
            "created_at": "2022-01-04 17:11:35",
            "delivered_at": "false",
            "username": "Kogol"
        },
        {
            "created_at": "2022-01-04 17:11:55",
            "delivered_at": "2022-01-05 17:31:35",
            "username": "Kogol"
        }
    ],
    "vote_streak": 2,
    "votes_count": 2,
    "username": "Kogol",
    "next_vote_at": "2022-01-04 17:23:54"
}

GET https://www.minecraft-list.cz/api/server/{slug}/player/{player}/next-vote

200 Vrátí čas dalšího možného hlasování a username hráče.

                        {
    "username": "Kogol",
    "next_vote_at": "2022-01-06 17:11:67"
}

Webhook (doručení hlasů)

Webhook je jednoduchá alternativa k Votifieru – nepotřebujete otevřený port. Při každém hlasu pošleme POST na vaši URL (nastavíte ji v sekci Nástroje → Webhook). V hlavičce X-Secret pošleme váš tajný klíč. Stačí ověřit, že se shoduje s tím vaším, a odměnit hráče.

POST {webhook_url}

Hlavička pro ověření:

X-Secret – váš tajný klíč. Porovnejte ho s vaším; pokud nesedí, požadavek odmítněte.

Tělo požadavku (JSON):

                        {
    "event": "vote",
    "vote_id": 12345,
    "username": "Kogol",
    "server": {
        "title": "Minecraft server name",
        "slug": "minecraft-server-name",
        "votes": 543
    },
    "service": "minecraft-list.cz",
    "timestamp": 1750000000
}

Příklad (PHP):

if (($_SERVER['HTTP_X_SECRET'] ?? '') !== 'VAS_TAJNY_KLIC') {
    http_response_code(401);
    exit;
}

$data = json_decode(file_get_contents('php://input'), true);
// odměňte hráče: $data['username']

Odpovězte stavovým kódem 2xx.
Při chybě hlas párkrát zopakujeme – stejný vote_id proto klidně ignorujte podruhé.
Neúspěšná doručení uvidíte v sekci Neodeslané hlasy.

Webhook (recenze)

Na stejnou URL a se stejnou hlavičkou X-Secret umíme posílat i události recenzí – hráče tak můžete odměnit za to, že o vašem serveru napsal recenzi. Události zapnete přepínačem Posílat i události recenzí v sekci Nástroje → Webhook. Ve výchozím stavu jsou vypnuté, aby endpoint, který čte jen username, nebral recenzi jako hlas.

POST {webhook_url}

Události (pole event):

review.created_first – hráč napsal první recenzi vašeho serveru. Tady hráče odměňte.
review.created_multiple – hráč už dříve recenzi tohoto serveru napsal (a smazal ji, nebo píše z jiného účtu se stejným nickem). Neodměňujte znovu.
review.updated – hráč upravil hodnocení nebo text své recenze.
review.deleted – recenzi smazal hráč nebo moderátor (např. kvůli porušení pravidel). Můžete odměnu odebrat.

Tělo požadavku (JSON):

                        {
    "event": "review.created_first",
    "review_id": 6789,
    "username": "Kogol",
    "rating": 5,
    "text": "Skvělý server, super komunita a žádné lagy.",
    "previous_reviews": 0,
    "server": {
        "title": "Minecraft server name",
        "slug": "minecraft-server-name",
        "votes": 543
    },
    "service": "minecraft-list.cz",
    "timestamp": 1750000000
}

Pole:

review_id – ID recenze. Stejné u všech událostí jedné recenze.
username – Minecraft nick, se kterým hráč hlasuje (recenzi může napsat až po 5 hlasech).
rating – počet hvězdiček 1–5.
text – text recenze, nebo null, pokud hráč dal jen hvězdičky.
previous_reviews – kolik recenzí tohoto serveru stejný hráč (účet nebo nick) napsal dříve, včetně smazaných. U review.created_first je vždy 0.
timestamp – čas události (Unix).

Příklad (PHP):

if (($_SERVER['HTTP_X_SECRET'] ?? '') !== 'VAS_TAJNY_KLIC') {
    http_response_code(401);
    exit;
}

$data = json_decode(file_get_contents('php://input'), true);

switch ($data['event']) {
    case 'vote':
        // odměna za hlas: $data['username']
        break;
    case 'review.created_first':
        // odměna za první recenzi – pro jistotu si uložte $data['review_id']
        // a $data['username'] a odměňte každý nick jen jednou
        break;
    case 'review.deleted':
        // případně odměnu odeberte
        break;
}

http_response_code(200);

Odpovězte stavovým kódem 2xx i na události, které nezpracováváte.
Při chybě doručení to párkrát zopakujeme – stejnou kombinaci event + review_id proto podruhé ignorujte.
Recenzi zkusíte bez čekání na hráče tlačítkem Test recenze – pošle review.created_first s review_id 0.