WAPI – Handbuch

In diesem Artikel erfahren Sie:

• Wie WAPI funktioniert
  • Unterstützte Dienste
  • Einschränkungen der Anfragen
  • Synchrone und asynchrone Anfragen
  • Antwortcodes
• Wie Sie WAPI in der WEDOS Global Administration aktivieren
• Wie Sie WAPI in Ihr System integrieren
• Grundlegende Anfragen zum Testen der WAPI-Funktionen
• Behebung häufiger Probleme
• Häufig gestellte Fragen

---

WEDOS API (WAPI)

Die WEDOS API, kurz WAPI, dient dazu, WEDOS-Dienste direkt aus Ihrem System über Anfragen und Antworten zu verwalten.

• Die Kommunikation erfolgt entweder synchron (eine Antwort wird in der Regel innerhalb von Sekunden nach Eingang der Anfrage verarbeitet) oder asynchron (einige Antworten können längere Zeit in Anspruch nehmen; der Ablauf wird über Benachrichtigungen verfolgt).
• Die Daten werden über das Protokoll HTTPS mit der Methode POST im Parameter request übergeben; die Datenkodierung ist UTF-8.
• Unterstützte Formate sind sowohl XML und JSON.

Unterstützte Dienste

WAPI unterstützt derzeit die folgenden WEDOS Global Dienste:

• WEDOS Global Mitglieder
• WEDOS Protection
• WEDOS DNS und NSSET

Darüber hinaus können Sie auf die Dienste der Domain-Registrierungsstelle WEDOS zugreifen:

• Domains
• Domainkontakte
• Guthabenkonto

Einschränkungen von WAPI

Zum Schutz vor Missbrauch gelten bei WAPI die folgenden Einschränkungen:

• Ein Benutzerkonto kann maximal 1000 Anfragen pro Stunde senden. Dies gilt für alle Arten von Anfragen. Ist dieses Limit erreicht, weist WAPI weitere Anfragen ab, bis das Zeitlimit abgelaufen ist.
• Ein Benutzerkonto darf maximal 100 Anfragen zur Domainverfügbarkeit pro Stunde stellen. Dies gilt für die Anfragen domain-check, domain-create und domain-transfer-check.
• Wiederholt fehlerhafte Anfragen (fehlgeschlagene Autorisierung, Zugriff von einer nicht zugelassenen IP-Adresse, falsche Eingaben, fehlende oder falsche Parameter, unbekannte Befehle, Befehle, die zu einem beliebigen Fehler führen, oder Anfragen außerhalb der übrigen Einschränkungen) führen dazu, dass die IP-Adresse für jede fehlerhafte Anfrage über 10 hinaus für 1 Minute gesperrt wird. Mit jeder weiteren fehlerhaften Anfrage verlängert das System die Sperrzeit.

Synchrone und asynchrone Anfragen

Die meisten über WAPI ausgeführten Anfragen sind synchron – Sie senden die Anfrage und erhalten das Ergebnis in der Regel innerhalb weniger Sekunden.

Einige Anfragen sind asynchron – ihre Verarbeitung kann sehr lange dauern (sogar Stunden oder Tage). In solchen Fällen gibt WAPI nicht das Endergebnis zurück, sondern nur die Information über den Eingang der Anfrage. Das System sendet Ihnen anschließend Informationen über den Verlauf und das Endergebnis in Form von Benachrichtigungen.

Antwortcodes

Antwortcodes geben den Status einer WAPI-Antwort an. Einige Codes sind anfragespezifisch und in der jeweiligen WAPI-Dokumentation zu finden; die folgende Liste gilt für alle Anfragen.

• 1000 = OK
• 2000 = Fehler beim Parsen der Anfrage
• 2001 = Ungültige Anfrage – erforderlicher Parameter fehlt: user
• 2002 = Ungültige Anfrage – erforderlicher Parameter fehlt: auth
• 2003 = Ungültige Anfrage – erforderlicher Parameter fehlt: command
• 2004 = Ungültige Anfrage – nur ein data-Element ist zulässig
• 2005 = Ungültige Anfrage – Parameter clTRID ist zu lang
• 2006 = Limit der Anfragen überschritten
• 2007 = Ungültige Anfrage – maximale Anfragegröße überschritten
• 2008 = Ungültige Anfrage – Anfrage ist zu komplex
• 2009 = Ungültige Anfrage – Anfrage ist leer
• 2010 = Unbekannter Befehl
• 2011 = Befehl deaktiviert
• 2050 = Authentifizierung fehlgeschlagen
• 2051 = Zugriff von dieser IP-Adresse nicht erlaubt
• 2052 = IP-Adresse wegen zu vieler fehlgeschlagener Anfragen vorübergehend gesperrt
• 2100 = Erforderlicher Parameter fehlt
• 2101 = Parameter stimmen nicht überein
• 2102 = Ungültige Anfrage – Kodierung der Eingabedaten stimmt nicht überein
• 4000 = Interner Fehler
• 4001 = Interne Ausnahme
• 5000 = Schwerwiegender Fehler
• 5001 = Interner Authentifizierungsfehler
• 5003 = Außer Betrieb

---

WAPI aktivieren

Bevor Sie WAPI nutzen können, müssen Sie es aktivieren. Gehen Sie dazu wie folgt vor:

1. Melden Sie sich an in der WEDOS Global Administration ⧉.
2. Wählen Sie in der linken Leiste WAPI.
3. Im Formular WAPI-Einrichtung geben Sie Folgendes ein und bestätigen es mit der Festlegen -Schaltfläche:
   • Erlaubte IPs: Eine durch Kommas getrennte Liste von IP-Adressen (sowohl IPv4 als auch IPv6, CIDR-Notation wird unterstützt), von denen aus sich Ihr System mit WAPI verbindet.
   • Notification Mode: Die Art des Empfangs von Benachrichtigungen über den Verlauf asynchroner Anfragen.
   • Preferred Protocol: Diese Einstellung gilt nur für Systembenachrichtigungen. Antworten haben dasselbe Format wie die Anfragen.
4. Im Formular Passworteinstellungen geben Sie das WAPI-Passwort ein (zweimal zur Bestätigung) und klicken auf die Festlegen -Schaltfläche.

Die Einstellungen werden innerhalb von 30 Minuten wirksam.

---

WAPI in Ihr System integrieren

Um WAPI nach der Aktivierung in Ihr System zu integrieren, müssen Sie:

• Ein Skript für die Verbindung zur API einrichten
• Eine Anfrage senden
• Eine Antwort empfangen und verarbeiten
• Eine Benachrichtigung empfangen und verarbeiten

Verbindung zu WAPI

Für die Verbindung Ihres Systems mit WAPI benötigen Sie:

• Ihre WEDOS Anmelde-E-Mail und das WAPI-Passwort
• Die WAPI-URL (abhängig vom Format):
  • XML:https://api.wedos.com/wapi/xml
  • JSON:https://api.wedos.com/wapi/json

WAPI verwendet eine einzige Authentifizierungszeichenfolge, die ein SHA-1-Hash aus dem Benutzernamen, dem SHA-1-Hash des WAPI-Passworts und der aktuellen Stunde (00-23) ist. Die Zeitzone ist Europe/Prague (UTC+1 CET bzw. UTC+2 CET mit Sommerzeit). Ein konkretes Beispiel finden Sie im Code unten.

Die folgende Vorlage zeigt die Verbindung zu WAPI mithilfe eines PHP-Skripts:

<?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=' . urlencode($post));
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
$res = curl_exec($ch);
curl_close($ch);
?>

WAPI-Anfrage

Eine WAPI-Anfrage besteht aus den folgenden Daten:

• test: Kennzeichen für den Testmodus, optional. Wenn Sie in der Anfrage ein test-Element mit dem Wert 1 mitsenden, prüft WAPI nur den Befehl, nimmt aber keine Änderungen im System vor.
• user: Der Login (E-Mail) Ihres WEDOS Kundenkontos, erforderlich.
• auth: Autorisierungszeichenfolge, erforderlich. Dies ist ein SHA-1-Hash aus dem Benutzernamen, dem SHA-1-Hash des WAPI-Passworts und der aktuellen Stunde (00-23). Die Zeitzone ist Europe/Prague (UTC+1 CET bzw. UTC+2 CET mit Sommerzeit). Ein konkretes Beispiel finden Sie im Code unten.
• -Befehl: Die eigentliche WAPI-Anfrage. Erforderlich.
• clTRID: Kennung der Anfrage, optional. In dieses Element können Sie eine beliebige Zeichenfolge als Kennung eintragen, die WAPI in der Antwort zurückgibt.
• data: Der Datenteil der Anfrage. Optional.

Nachfolgend eine Vorlage für eine JSON-Anfrage:

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

WAPI-Antwort

Die Antwort besteht aus den folgenden Daten:

• code: Der Rückgabewert für die jeweilige Anfrage. Weitere Informationen zu diesen Codes finden Sie im Kapitel Antwortcodes und in der Dokumentation des jeweiligen Befehls.
• result: Beschreibung des Rückgabecodes.
• timestamp: Ausführungszeit des Befehls im UNIX-Format.
• clTRID: Kennung der Anfrage aufseiten des Kunden.
• svTRID: Kennung der Anfrage aufseiten des Servers.
• -Befehl: WAPI-Anfrage.
• data: Rückgabedaten. Keine, wenn die Anfrage fehlschlägt.
• test: Bei Antworten auf Testanfragen enthalten.

Nachfolgend eine Vorlage für eine JSON-Antwort:

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

Benachrichtigungen

Asynchrone Anfragen können nicht sofort ausgeführt werden. Den Verlauf und das Ergebnis solcher Operationen können Sie über Benachrichtigungen verfolgen. Synchrone Anfragen verwenden keine Benachrichtigungen.

Wenn WAPI die Operation nicht sofort abschließen kann, gibt es in der Antwort Request pending (1001) zurück. Nach Abschluss der Operation (bei komplizierteren Aktionen der einzelnen Schritte) erstellt es eine Benachrichtigung, die einer klassischen Antwort ähnelt. Die Benachrichtigung können Sie der entsprechenden Anfrage anhand der Parameter clTRID oder svTRID zuordnen.

Die Daten der Benachrichtigungen sind immer in UTF-8 kodiert.

Benachrichtigungen können Sie auf folgende Weisen empfangen (je nach Einstellung):

• Über die POLL-Warteschlange.
• Versand an eine angegebene E-Mail-Adresse.
• Über das HTTP- (oder HTTPS-)Protokoll an die von Ihnen angegebene URL-Adresse mit der POST-Methode im Parameter request. Als Erfolg gilt eine HTTP-Antwort mit dem Rückgabecode 200. Schlägt die Zustellung fehl, versucht das System die Benachrichtigung in Abständen von mehreren Minuten erneut zuzustellen.

Nachfolgend finden Sie eine Vorlage einer JSON-Benachrichtigung:

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

---

Grundlegende Anfragen

Zu den grundlegenden Anfragen gehören ping, ping-async, sowie Befehle für die Arbeit mit der POLL-Warteschlange poll-req und poll-ack.

ping

Die ping -Anfrage dient zum Testen der WAPI-Funktionalität – zum Beispiel der Anmeldedaten, der IP-Adresse oder des Codes.

Die Rückgabewerte sind:

• 1000 – OK

Vorlage der JSON-Anfrage:

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

Vorlage der JSON-Antwort:

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

ping-async

Die ping-async -Anfrage testet die Funktionalität der WAPI-Benachrichtigungen.

Die Rückgabewerte sind:

• 1000 – OK
• 1001 – Warten auf die Anfrage

Vorlage der JSON-Anfrage:

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

Vorlage der JSON-Antwort:

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

Vorlage der JSON-Benachrichtigung:

{
  "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 und poll-ack

Benachrichtigungen aus der POLL-Warteschlange können Sie durch die Kombination der Befehle poll-req und poll-ack :

1. Verwenden Sie poll-req als Befehl zum Abrufen der ältesten verfügbaren Benachrichtigung.
2. Mit dem Befehl poll-ack markieren Sie die Benachrichtigung als gelesen und geben neuere frei, bis die Warteschlange geleert ist.

Die Rückgabewerte für poll-req sind:

• 1000 – Benachrichtigung empfangen
• 1003 – keine ungelesene Benachrichtigung in der Warteschlange
• 2150 – Benachrichtigungen der POLL-Warteschlange sind für dieses Konto deaktiviert

JSON poll-req Vorlage der Anfrage:

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

JSON poll-req Vorlage der Antwort (Benachrichtigung verfügbar):

{
  "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 Vorlage der Antwort (leere Benachrichtigungswarteschlange):

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

Die folgenden Parameter gehören in die poll-ack -Anfrage:

• id – aktuelle Kennung der poll-Benachrichtigung

Die Rückgabewerte für poll-ack sind:

• 1002 – Benachrichtigung als gelesen markiert
• 2151 – Benachrichtigung nicht gefunden

JSON poll-ack -Anfrage:

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

JSON poll-ack Antwort:

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

---

Behebung häufiger Probleme

Zu den häufigen Problemen mit WAPI gehören:

• Fehlgeschlagene Authentifizierung von Anfragen

---

FAQ