WAPI - Manuel

Dans cet article, vous apprendrez :

• Fonctionnement de l'interface WAPI
  • Services d'aide
  • Demande de restrictions
  • Demandes synchrones et asynchrones
• Comment activer l'interface WAPI dans le panneau d'administration de WEDOS Global ?
• Comment intégrer l'interface WAPI dans votre système
• Demandes de base pour tester les fonctionnalités de l'interface WAPI
• Dépannage des problèmes courants
• Questions fréquemment posées

---

API WEDOS (WAPI)

L'API WEDOS, en abrégé WAPI, est utilisée pour gérer les services WEDOS directement à partir de votre système par le biais de demandes et de réponses.

• La communication est soit synchrone (une réponse est généralement traitée dans les secondes qui suivent la réception de la demande), soit asynchrone (certaines réponses peuvent prendre plus de temps ; le processus est contrôlé par des notifications).
• Les données sont transmises via le protocole HTTPS par la méthode POST dans le paramètre de requête ; le codage des données est UTF-8.
• Les formats pris en charge sont XML et JSON.

Services de soutien

L'interface WAPI prend actuellement en charge les services WEDOS Global suivants :

• Membres de WEDOS Global
• Protection WEDOS
• WEDOS DNS et NSSET

En outre, vous pouvez accéder aux services d'enregistrement de domaines de WEDOS :

• Domaines
• Contacts dans le domaine
• Compte de crédit

Restrictions WAPI

Pour éviter les abus, l'interface WAPI applique les restrictions suivantes :

• Un compte d'utilisateur peut envoyer un maximum de 1000 demandes par heure. Cette limite s'applique à tous les types de demandes. Lorsque cette limite est atteinte, l'interface WAPI rejette les autres demandes jusqu'à ce que le délai d'attente soit écoulé.
• Un compte d'utilisateur est autorisé à effectuer un maximum de 100 demandes de disponibilité de domaine par heure. Ceci s'applique aux demandes de contrôle de domaine, de création de domaine et de contrôle de transfert de domaine.
• Les demandes répétées non valables (échec de l'autorisation, accès à partir d'une adresse IP non autorisée, saisie incorrecte, paramètres manquants ou incorrects, commandes inconnues, commandes entraînant une erreur, ou toute demande dépassant d'autres restrictions) entraîneront le blocage de l'adresse IP pendant 1 minute pour chaque demande non valide au-delà de 10. Le système augmente la durée de blocage pour chaque demande non valide supplémentaire.

Demandes synchrones et asynchrones

La plupart des requêtes exécutées via l'interface WAPI sont synchrones - vous envoyez la requête et vous obtenez généralement le résultat en quelques secondes.

Certaines demandes sont asynchrones - leur traitement peut prendre beaucoup de temps (même des heures ou des jours). Dans ce cas, l'interface WAPI ne renvoie pas le résultat final, mais uniquement des informations sur la réception de la demande. Le système vous envoie alors des informations sur la progression et le résultat final sous la forme de notifications.

---

Activer l'interface WAPI

Avant de commencer à utiliser l'interface WAPI, vous devez l'activer. Pour ce faire, procédez comme suit :

1. Connectez-vous au panneau d'administration de WEDOS Global &boxbox ;.
2. Dans la barre de gauche, sélectionnez WAPI.
3. Dans le cadre de la Configuration de l'interface WAPI Saisissez les données suivantes et confirmez à l'aide de la touche Set (jeu de mots) bouton :
   • IP autorisées : Liste d'adresses IP (IPv4 et IPv6) séparées par des virgules, à partir desquelles votre système se connecte à l'interface WAPI.
   • Méthode de notification : Méthode permettant de recevoir des notifications sur l'état d'avancement des demandes asynchrones.
   • Protocole préféré : Ce paramètre ne s'applique qu'aux notifications du système. Les réponses utilisent le même format que les demandes.
4. Dans le formulaire Paramètres du mot de passe, saisissez le mot de passe WAPI (deux fois pour le confirmer) et cliquez sur le bouton Définir.

Les réglages prendront effet dans les 30 minutes.

---

Intégrer l'interface WAPI dans votre système

Pour intégrer l'interface WAPI dans votre système une fois qu'elle a été activée, vous devez.. :

• Mettre en place un script pour se connecter à l'API
• Envoyer une demande
• Recevoir et traiter une réponse
• Recevoir et traiter une notification

Connexion à l'interface WAPI

Pour connecter votre système à l'interface WAPI, vous aurez besoin des éléments suivants :

• Votre email de connexion WEDOS et votre mot de passe WAPI
• L'URL WAPI (en fonction du format) :
  • XML : https://api.wedos.com/wapi/xml
  • JSON : https://api.wedos.com/wapi/json

L'interface WAPI accepte une seule chaîne d'authentification, qui est un hachage sha1 d'une chaîne composée du nom d'utilisateur, du hachage sha1 du mot de passe WAPI et de l'heure actuelle (00-23). Le fuseau horaire est Europe/Prague (UTC+1 CET, ou UTC+2 CET avec ajustement DST). Voir le code ci-dessous pour un exemple spécifique.

Le modèle suivant illustre la connexion à l'interface WAPI à l'aide d'un script PHP :

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'your@login.tld'; 
$wpass = 'your-WAPI-password'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'request name',
  'data' => ['request data'],
  'clTRID' => 'request identifier',
  'test' => '1 (if you only want to test the request)'
  ]
];

$post = json_encode($input);
$ch = curl_init($url);
curl_setopt($ch,CURLOPT_TIMEOUT,60);
curl_setopt($ch,CURLOPT_POST,true);
curl_setopt($ch,CURLOPT_POSTFIELDS, 'request=' . $post);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
$res = curl_exec($ch);
?>

Demande WAPI

Une demande WAPI se compose des données suivantes :

• test: Indicateur de mode de test, facultatif. Si vous incluez un élément test d'une valeur de 1 dans la demande, l'interface WAPI ne fera que vérifier la commande, mais n'apportera aucune modification au système.
• utilisateur: Votre identifiant de compte client WEDOS (email), obligatoire.
• auth: Chaîne d'autorisation, obligatoire. Il s'agit d'un hachage sha1 d'une chaîne composée du nom d'utilisateur, du hachage sha1 du mot de passe WAPI et de l'heure actuelle (00-23). Le fuseau horaire est Europe/Prague (UTC+1 CET, ou UTC+2 CET avec ajustement DST). Voir le code ci-dessous pour un exemple spécifique.
• commande: La demande WAPI proprement dite. Elle est obligatoire.
• clTRID: ID de la demande, facultatif. Vous pouvez insérer dans cet élément n'importe quelle chaîne de caractères en tant qu'identifiant que l'interface WAPI renverra dans la réponse.
• données: La partie "données" de la demande. Facultatif.

Voici un modèle de demande JSON :

{
  "request":
  {
    "user": "your@login.tld",
    "auth": "auth-string",
    "command": "request-name",
    "data":
    {
      request data
    }
    "clTRID": "request-id (optional)",
  }
}

Réponse de l'interface WAPI

La réponse se compose des données suivantes :

• code: La valeur de retour pour la demande donnée. Vous trouverez plus d'informations sur ces codes dans la documentation spécifique de la commande.
• résultat: Description du code de retour.
• horodatage: Heure d'exécution de la commande au format UNIX.
• clTRID: Identifiant de la demande du client.
• svTRID: Identifiant de la demande du serveur.
• commande: Demande WAPI.
• données: Données de retour. Aucune si la demande échoue.
• test: Inclus dans les réponses aux demandes de test.

Voici un modèle de réponse JSON :

{
  "response": {
    "code": "numerical code",
    "result": "message",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "request-name"
  }
}

Notifications

Les requêtes asynchrones ne peuvent pas être exécutées immédiatement. Vous pouvez suivre la progression et le résultat de ces opérations par le biais de notifications. Les requêtes synchrones n'utilisent pas de notifications.

Si l'interface WAPI ne peut pas terminer l'opération immédiatement, elle renvoie Request pending (1001) en réponse. Une fois l'opération terminée (pour les actions plus complexes comportant des étapes individuelles), elle crée une notification similaire à une réponse classique. Vous pouvez faire correspondre la notification à la demande correspondante à l'aide des paramètres clTRID ou svTRID.

Les données de notification sont toujours encodées en UTF-8.

Vous pouvez recevoir des notifications de la manière suivante (en fonction des paramètres) :

• Utilisation de la file d'attente POLL.
• Envoyer à l'adresse électronique spécifiée.
• Via le protocole HTTP (ou HTTPS) à l'adresse URL que vous avez spécifiée en utilisant la méthode POST dans le paramètre de requête. Une réponse HTTP avec un code de retour de 200 est considérée comme un succès. En cas d'échec, le système tentera d'envoyer à nouveau la notification à plusieurs minutes d'intervalle.

Voici un modèle de notification JSON :

{
  "notify": {
    "code": "numerical code",
    "result": "message",
    "timestamp": "UTF time",
    "svTRID": "server request id",
    "command": "request-name",
    "ID": "numerical id"
  }
}

---

Demandes de base

Les requêtes de base comprennent ping, ping-async, et les commandes pour travailler avec la file d'attente POLL poll-req et poll-ack.

ping

La requête ping est utilisée pour tester la fonctionnalité de l'interface WAPI - par exemple, les identifiants de connexion, l'adresse IP ou le code.

Les valeurs de retour sont les suivantes :

• 1000 - OK

Modèle de demande JSON :

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "ping",
    "clTRID": "user request id"
  }
}

Modèle de réponse JSON :

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping"
  }
}

ping-async

La requête ping-async teste la fonctionnalité des notifications WAPI.

Les valeurs de retour sont les suivantes :

• 1000 - OK
• 1001 - En attente d'une demande

Modèle de demande JSON :

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "ping",
    "clTRID": "user request id"
  }
}

Modèle de réponse JSON :

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping"
  }
}

Modèle de notification JSON :

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping-async",
    "id": "poll queue id",
    "data": {
      "round": "attempt number",
      "time": "time",
      "done": 1
    }
  }
}

poll-req et poll-ack

Vous pouvez recevoir des notifications de la file d'attente POLL en combinant les commandes poll-req et poll-ack:

1. Utilisez la commande poll-req pour télécharger la plus ancienne notification disponible.
2. La commande poll-ack permet de marquer la notification comme lue et de mettre à disposition les nouvelles notifications jusqu'à ce que la file d'attente soit épuisée.

Les valeurs de retour pour poll-req sont les suivantes :

• 1000 - notification reçue
• 1003 - aucune notification non lue dans la file d'attente
• 2150 - les notifications de la file d'attente sont désactivées pour ce compte

JSON poll-req modèle de demande :

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "poll-req",
    "clTRID": "user request id"
  }
}

JSON poll-req (notification disponible) :

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "UTF time",
        "clTRID": "request user id",
        "svTRID": "request server id",
        "command": "request name",
        "id": "poll queue id"
      }
    }
  }
}

JSON poll-req (file d'attente de notification vide) :

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": “1286962852”,
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-req"
  }
}

Inclure les paramètres suivants dans la requête poll-ack :

• id - ID de la notification de sondage en cours

Les valeurs de retour pour poll-ack sont les suivantes :

• 1002 - notification marquée comme lue
• 2151 - notification non trouvée

JSON poll-ack demande :

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "poll-ack",
    "clTRID": "user request id",
    "data": {
      "id": “poll notification id”
    }
  }
}

JSON poll-ack réponse :

{
  "response": {
    "code": “1002”,
    "result": "Notification acquired",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-ack"
  }
}

---

Dépannage des problèmes courants

Les problèmes courants liés à l'interface WAPI sont les suivants

• Absence d'authentification des demandes

---

FAQ