# 🌐 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

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 :

Créez un keystore Java :

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

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