L’API MineList permet à ton serveur de vérifier si un joueur a voté, de donner une récompense exactement une fois et de lire les statistiques publiques. Tous les endpoints renvoient du JSON et utilisent de simples requêtes HTTPS GET : ils fonctionnent donc avec n’importe quel langage.
Obtenir ta clé API
Ajoute ton serveur, revendique-le et ouvre le panneau du propriétaire. La clé API s’affiche sur la page des paramètres du serveur. Garde-la secrète, car elle identifie ton serveur. Si elle fuite, génère-en une nouvelle dans le panneau et mets à jour ton plugin ou ton script.
L’adresse de base de tous les endpoints est https://minelist.eu.
Vérifier un vote
GET /api/v1/vote?key=API_KEY&username=NICKIndique si le joueur a voté aujourd’hui et si la récompense a déjà été récupérée.
{"voted":true,"claimed":false,"next_vote_utc":"2026-10-31T00:00:00Z"}votedvaut true si le pseudo a un vote pour ton serveur pendant la journée UTC en cours.claimedvaut true si tu as déjà marqué ce vote comme récupéré.next_vote_utcest l’heure à laquelle le joueur pourra voter à nouveau.
Récupérer un vote
GET /api/v1/vote/claim?key=API_KEY&username=NICKMarque le vote du jour comme récupéré. Appelle-le juste avant de donner la récompense, pour qu’un joueur ne puisse pas la toucher deux fois. Réponses possibles :
| Réponse | Signification |
|---|---|
{"voted":true,"claimed":true} | Le vote était valide et il est maintenant récupéré. Donne la récompense. |
{"voted":true,"claimed":false,"already_claimed":true} | Le vote avait déjà été récupéré auparavant. Ne donne rien. |
{"voted":false,"claimed":false} | Le joueur n’a pas voté aujourd’hui. |
Lister les votes du mois
GET /api/v1/votes?key=API_KEYRenvoie tous les votes reçus par ton serveur pendant le mois en cours. C’est utile pour les récompenses mensuelles des meilleurs votants et pour les classements sur ton propre site.
Statistiques publiques du serveur
GET /api/v1/server/<slug>Cet endpoint ne nécessite aucune clé. Le slug est la dernière partie de l’adresse du serveur sur MineList. Exemples de champs de la réponse :
| Champ | Description |
|---|---|
name | Nom du serveur |
url | Site web du serveur |
ip | Adresse de connexion |
online | Indique si la dernière vérification a réussi |
players | Joueurs en ligne lors de la dernière vérification |
max_players | Nombre de places |
version | Version du serveur |
votes_month | Votes ce mois-ci |
votes_total | Votes depuis l’ajout du serveur |
uptime_30 | Disponibilité sur les 30 derniers jours, en pourcentage |
rating | Note moyenne |
last_check | Heure de la dernière vérification |
Exemple avec curl
Voici toute la logique sous forme de commande shell. N’importe quel langage capable d’envoyer une requête HTTP, comme Java, PHP, Python ou Node.js, fait la même chose.
curl -s "https://minelist.eu/api/v1/vote/claim?key=API_KEY&username=Steve"Analyse le JSON et, si claimed vaut true, exécute ta commande de récompense, par exemple give Steve diamond 3.
Prise en charge de NuVotifier
Si tu préfères des récompenses instantanées sans interroger l’API en permanence, MineList peut envoyer les votes à ton serveur via NuVotifier. Les deux versions du protocole sont prises en charge. La version 1 utilise une clé publique RSA, la version 2 un token.
- Installe NuVotifier sur ton serveur et redémarre-le.
- Dans le panneau du propriétaire, saisis l’hôte, le port (8192 par défaut) et la clé publique (v1) ou le token (v2).
- Clique sur Envoyer un vote test et vérifie que ton serveur enregistre le vote dans ses logs.
Si le test échoue, vérifie que le port de Votifier est ouvert dans ton pare-feu et que la clé a été copiée sans espaces ni retours à la ligne.
Bannière en direct
Chaque serveur dispose d’une bannière en direct de 468x60 pixels qui affiche l’état actuel et le nombre de joueurs :
https://minelist.eu/banner/<slug>.pngExemple d’intégration en HTML :
<a href="https://minelist.eu/fr/server/ton-slug">
<img src="https://minelist.eu/banner/ton-slug.png" width="468" height="60" alt="Vote pour nous sur MineList">
</a>Bonnes pratiques
- Mets les statistiques publiques en cache pendant au moins une minute au lieu d’appeler l’API à chaque affichage de page.
- Ne mets jamais la clé API dans du code côté client ni dans un dépôt public.
- N’appelle l’endpoint de récupération qu’une seule fois par récompense.