API dokumentaci | Minecraft-list.cz

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.