Documentation API

Intégrez vos données Hytale Top Serveur dans vos sites web, bots Discord ou plugins Java.

L'API Hytale Top Serveur est une interface REST JSON. Elle est conçue pour être simple d'utilisation et performante. L'URL de base pour toutes les requêtes est :

https://hytale-top-serveur.fr/api/v1

Vous préférez une solution clé en main ?

Utilisez notre plugin officiel ServerWebLink pour gérer les récompenses automatiquement sur votre serveur Java sans coder.

Configurer le plugin

Authentification

Certaines routes (comme la vérification de vote) sont privées et nécessitent une authentification. Vous devez fournir votre api_key via le header HTTP x-api-key.

Votre clé API est secrète. Ne l'exposez jamais dans du code client (JavaScript navigateur). Utilisez-la uniquement côté serveur.

Example Request
curl -H "x-api-key: YOUR_SECRET_KEY" \
  https://.../api/v1/resource
GET

Informations Serveur

Récupère les informations publiques d'un serveur spécifique. Idéal pour afficher le nombre de votes ou le classement sur votre propre site web.

Endpoint

/server/:id

Paramètres

  • id(string)- L'UUID de votre serveur.
Response Example200 OK
{
  "success": true,
  "data": {
    "id": "123e4567-...",
    "name": "Hytale Server",
    "status": "online",
    "votes": 1250,
    "rank": 4,
    "connection": {
      "ip": "play.server.com",
      "port": 25565
    }
  }
}
PRIVATE

Vérification de Vote

Vérifie si un joueur a des votes en attente pour votre serveur. Le système de Cumul (Stacking) permet de compter plusieurs votes non encore réclamés.

Endpoint

/server/:id/vote/check

Paramètres Query

Vous devez fournir soit ip soit username.

  • username(string, recommandé)- Le pseudo du joueur (ex: "Steve"). IDÉAL pour les récompenses en jeu.
  • ip(string)- L'adresse IP du joueur.

Headers

  • x-api-key- Votre clé API secrète.
Response Example200 OK
{
  "hasVoted": true,
  "claimed": false,
  "unclaimedCount": 3,
  "nextVoteWait": "1h 20m"
}
Java (OkHttp)
Request request = new Request.Builder()
  .url("https://.../api/v1/server/123/vote/check?username=Steve")
  .addHeader("x-api-key", "YOUR_KEY")
  .build();
PRIVATE POST

Réclamation (Claim)

Marque tous les votes en attente d'un joueur comme "réclamés". Cette action doit être effectuée lorsque votre serveur a effectivement donné la (ou les) récompense(s) au joueur en jeu. Cela vide le compteur unclaimedCount du joueur pour ce serveur.

Endpoint

/server/:id/vote/claim

Body (JSON)

  • username(string)- Le pseudo du joueur.

Headers

  • x-api-key- Votre clé API secrète.
Response Example200 OK
{
  "success": true,
  "message": "3 vote(s) claimed successfully",
  "claimedCount": 3
}
Exemple CURL (POST)
curl -X POST "https://.../api/v1/server/123/vote/claim" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "Steve"}'
HTTP PUSH

Push API (Statistiques)

Cette API permet à votre serveur de nous envoyer ses statistiques en temps réel (joueurs, RAM, uptime, plugins). C'est la méthode recommandée pour une intégration parfaite.

Endpoint

POST /server/:id/push-stats

Headers

  • x-api-key : Votre clé API secrète
  • Content-Type : application/json

💡 Watchdog

Si aucun pulse n'est reçu pendant plus de 5 minutes, le serveur est automatiquement marqué comme Hors-ligne.

Payload Example (JSON)
{
  "players": 42,
  "max_players": 100,
  "status": "online",
  "uptime": 3600000,
  "memory_used": 2048,
  "memory_max": 8192,
  "worlds": ["Lobby", "Survival"],
  "plugins": [
    {"name": "ServerWebLink", "version": "1.0", "enabled": true}
  ]
}
Exemple CURL
curl -X POST "https://.../api/v1/server/123/push-stats" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"players": 42, "max_players": 100, "status": "online"}'

Mes Clés API & Tests

Espace Privé

Authentification requise

Vous devez être connecté pour voir et gérer les clés API de vos serveurs.

Se connecter