Horizons
🔌 API

🌐 API Web

📂 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

EndpointDescriptionMĂ©thodeAuthentification
/api/teamsRécupérer les informations des équipesGETClé secrÚte
/api/playersRécupérer les informations des joueursGETClé secrÚte
/api/shopsRécupérer les données des boutiquesGETClé 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

OptionDescriptionValeur par défaut
enabledActive ou désactive l'APIfalse
secretClĂ© secrĂšte pour authentifier les requĂȘtesGĂ©nĂ©rĂ© automatiquement
modeMode d'hébergement (self-hosted ou external)self-hosted
portPort d'Ă©coute pour l'API8080
https.enabledActive ou désactive HTTPSfalse
https.keystore_pathChemin vers le fichier keystore pour HTTPS""
https.keystore_passwordMot de passe du keystore""
https.domainNom de domaine pour l'API""
rate_limit.max_per_minuteLimite de requĂȘtes par minute par adresse IP60

🔐 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 :

CommandeDescriptionPermission
/api startDĂ©marre l'API Webhorizons.admin.api
/api stopArrĂȘte l'API Webhorizons.admin.api
/api statusAffiche le statut et les informations de l'APIhorizons.admin.api
/api helpAffiche l'aide de la commandehorizons.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

PermissionDescription
horizons.admin.apiPermet 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

☕ API Java & Modules

Previous Page

🔧 Skript

Next Page

On this page

📂 Structure de l'APIPoints d'accĂšs disponiblesđŸ› ïž ConfigurationOptions disponibles🔐 SĂ©curitĂ©AuthentificationLimites de dĂ©bitđŸ’» Commandes🔄 Format des rĂ©ponsesÉquipes (/api/teams)Joueurs (/api/players)Boutiques (/api/shops)🔗 IntĂ©gration HTTPS💡 Exemples d'utilisationRĂ©cupĂ©rer les Ă©quipes avec cURLRĂ©cupĂ©rer les joueurs avec JavaScriptCrĂ©er un tableau des scores d'Ă©quipes avec PHPđŸ›Ąïž PermissionsđŸ§© IntĂ©gration avec des services externesđŸ€” DĂ©pannage