🌐API Web

Ce document présente comment configurer et utiliser l'API Web intégrée au plugin Horizons pour accéder aux données du serveur à distance.

📂 Structure de l'API

L'API Web de Horizons permet d'accéder aux données du serveur à travers des endpoints HTTP. Cela vous permet d'intégrer les données de votre serveur avec des sites web, applications mobiles, bots Discord, et plus encore.

Points d'accès disponibles

Endpoint	Description	Méthode	Authentification
/api/teams	Récupérer les informations des équipes	GET	Clé secrète
/api/players	Récupérer les informations des joueurs	GET	Clé secrète
/api/shops	Récupérer les données des boutiques	GET	Clé secrète

🛠️ Configuration

La fonctionnalité API est configurable dans le fichier config.yml :

#######################################
#           WEB API INTEGRATION       #
#######################################
api:
  enabled: false
  secret: "generatedsecretkey" # Sera généré automatiquement
  mode: "self-hosted" # ou "external"
  port: 8080
  https:
    enabled: false
    keystore_path: ""
    keystore_password: ""
    domain: ""

  # Limites pour éviter le flood
  rate_limit:
    max_per_minute: 60

Options disponibles

Option	Description	Valeur par défaut
enabled	Active ou désactive l'API	false
secret	Clé secrète pour authentifier les requêtes	Généré automatiquement
mode	Mode d'hébergement (self-hosted ou external)	self-hosted
port	Port d'écoute pour l'API	8080
https.enabled	Active ou désactive HTTPS	false
https.keystore_path	Chemin vers le fichier keystore pour HTTPS	""
https.keystore_password	Mot de passe du keystore	""
https.domain	Nom de domaine pour l'API	""
rate_limit.max_per_minute	Limite de requêtes par minute par adresse IP	60

🔐 Sécurité

L'accès à l'API est protégé par une clé secrète qui doit être incluse dans toutes les requêtes. Cette clé est générée automatiquement au premier démarrage du plugin ou peut être définie manuellement dans config.yml.

Authentification

Pour accéder à l'API, ajoutez le paramètre secret à vos requêtes :

http://votreserveur:8080/api/teams?secret=votreclesecrète

Limites de débit

Pour protéger votre serveur contre les abus, une limite de débit est appliquée par défaut :

• 60 requêtes par minute et par adresse IP

• Les requêtes dépassant cette limite recevront une réponse 401 Unauthorized

💻 Commandes

L'API peut être gérée avec la commande /api :

Commande	Description	Permission
/api start	Démarre l'API Web	horizons.admin.api
/api stop	Arrête l'API Web	horizons.admin.api
/api status	Affiche le statut et les informations de l'API	horizons.admin.api
/api help	Affiche l'aide de la commande	horizons.admin.api

🔄 Format des réponses

Équipes (/api/teams)

{
  "teams": [
    {
      "name": "fraude",
      "displayName": "&5Fraude Fiscale",
      "displayNameClean": "Fraude Fiscale",
      "prefix": "&5Fraude Fiscale &8-&5 ",
      "prefixClean": "Fraude Fiscale - ",
      "score": 125673,
      "players": [
        {
          "uuid": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Joueur1",
          "online": true
        },
        {
          "uuid": "550e8400-e29b-41d4-a716-446655440001",
          "name": "Joueur2",
          "online": false
        }
      ]
    }
  ]
}

Joueurs (/api/players)

{
  "players": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Joueur1",
      "score": 500,
      "team": "fraude",
      "online": true
    },
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Joueur2",
      "score": 350,
      "team": "Terre",
      "online": false
    }
  ]
}

Boutiques (/api/shops)

{
  "shops": [
    {
      "id": "general_shop::Shop_Keeper",
      "name": "Shop Keeper",
      "entityType": "VILLAGER",
      "items": [
        {
          "material": "DIAMOND_SWORD",
          "currentPrice": 500,
          "pricingType": "STATIC",
          "basePrice": 500
        },
        {
          "material": "GOLDEN_APPLE",
          "currentPrice": 120,
          "pricingType": "DYNAMIC",
          "basePrice": 120,
          "minPrice": 80,
          "maxPrice": 250
        }
      ]
    }
  ]
}

🔗 Intégration HTTPS

Pour une sécurité renforcée, vous pouvez activer HTTPS pour vos connexions API :

1. Créez un keystore Java :

keytool -genkey -alias horizons -keyalg RSA -keystore horizons.keystore -validity 365

1. Configurez HTTPS dans config.yml :

api:
  https:
    enabled: true
    keystore_path: "/chemin/vers/horizons.keystore"
    keystore_password: "motdepasse"
    domain: "api.votreserveur.com"

💡 Exemples d'utilisation

Récupérer les équipes avec cURL

curl "http://localhost:8080/api/teams?secret=generatedsecretkey"

Récupérer les joueurs avec JavaScript

fetch('http://localhost:8080/api/players?secret=generatedsecretkey')
  .then(response => response.json())
  .then(data => {
    console.log('Liste des joueurs:', data.players);
  })
  .catch(error => console.error('Erreur:', error));

Créer un tableau des scores d'équipes avec PHP

<?php
$apiUrl = 'http://localhost:8080/api/teams?secret=generatedsecretkey';
$response = file_get_contents($apiUrl);
$data = json_decode($response, true);

echo '<table border="1">';
echo '<tr><th>Équipe</th><th>Score</th></tr>';

foreach ($data['teams'] as $team) {
    echo '<tr>';
    echo '<td>' . htmlspecialchars($team['displayNameClean']) . '</td>';
    echo '<td>' . $team['score'] . '</td>';
    echo '</tr>';
}

echo '</table>';
?>

🛡️ Permissions

Permission	Description
horizons.admin.api	Permet d'utiliser toutes les commandes d'API

🧩 Intégration avec des services externes

L'API Web de Horizons peut facilement s'intégrer avec :

• Sites web personnalisés

• Applications mobiles iOS/Android

• Bots Discord

• Tableaux de classement en temps réel

• Systèmes de modération externes

🤔 Dépannage

• L'API ne démarre pas : Vérifiez que le port spécifié n'est pas déjà utilisé par un autre programme

• Erreur d'authentification : Assurez-vous que la clé secrète est correcte dans vos requêtes

• Limite de débit atteinte : Réduisez la fréquence de vos requêtes ou augmentez la limite dans la configuration

• Problèmes HTTPS : Vérifiez que votre keystore est valide et que le mot de passe est correct