WAPI – Handbuch

In diesem Artikel erfahren Sie:

• Wie WAPI funktioniert und wofür es dient
• Wie Sie WAPI in der Kundenadministration aktivieren
• Wie Kommunikation und Authentifizierung ablaufen
• Wie Sie in Listen blättern und suchen
• Grundbefehle
• Liste der Rückgabecodes
• Glossar

---

WEDOS API

Die WEDOS API, kurz WAPI, dient dazu, Dienste direkt aus Ihrem Informationssystem zu steuern. 

Voraussetzung für die Nutzung der Schnittstelle ist die Verwendung eines WEDOS Guthabenkontos, von dem das System die Zahlungen für Registrierungen, Verlängerungen, Transfers und weitere berechnete Gebühren abbucht.

WAPI ermöglicht derzeit die Verwaltung von:

• Guthabenkonto ⧉ (account-* und credit-*)
• Domains ⧉ (domains-* und domain-*)
• Domainkontakten ⧉ (contact-*)
• NSSET ⧉ (nsset-*)
• DNS ⧉ (dns-*)
• Berechtigten Benutzern von WEDOS Global ⧉ (wg-members-*)
• WEDOS Protection ⧉ (wgp-services-* und wgp-domain-*)

Einschränkungen von WAPI

Als Schutz vor Missbrauch wendet WAPI folgende Einschränkungen an:

• Über ein Benutzerkonto können Sie maximal 1000 Anfragen pro Stunde senden. Dies betrifft alle Anfragen aller Typen. Sobald dieses Limit erreicht ist, lehnt WAPI weitere Anfragen bis zum Ablauf des Zeitlimits ab.
• Ein Benutzerkonto darf maximal 100 Anfragen zur Verfügbarkeit einer Domain pro Stunde stellen. Dies betrifft die Befehle domain-check, domain-create und domain-transfer-check.
• Wiederholtes Senden ungültiger Anfragen (Autorisierungsfehler, Zugriff von einer nicht erlaubten IP-Adresse, fehlerhafte Eingabe, fehlende oder falsche Parameter, unbekannter Befehl, Befehle, die mit einem beliebigen Fehler enden, oder jede Anfrage, die über die übrigen Einschränkungen hinausgeht) führt bei Überschreitung von 10 ungültigen Anfragen zu einer Sperrung der IP-Adresse für 1 Minute pro ungültiger Anfrage. Mit jeder weiteren fehlerhaften Anfrage verlängert das System die Sperrdauer.

Synchrone und asynchrone Operationen

Die meisten über WAPI ausgeführten Befehle sind synchron – Sie senden einen Befehl und erhalten das Ergebnis in der Regel innerhalb weniger Sekunden. 

Einige Operationen sind asynchron, die Bearbeitung eines solchen Befehls kann also sehr lange dauern (auch Stunden oder Tage). WAPI liefert daher nicht das Endergebnis, sondern nur die Information, dass der Befehl angenommen wurde. Informationen zum Verlauf und das Endergebnis sendet Ihnen das System anschließend in Form von Benachrichtigungen.

Protokollierung

Das Anfrageprotokoll finden Sie in der Kundenadministration mit diesen Schritten:

1. Melden Sie sich in der Kundenadministration ⧉.
2. Wählen Sie im oberen Menü My Account Customer.
3. Wählen Sie im linken Menü WAPI queries.

---

WAPI in der Kundenadministration aktivieren

Bevor Sie WAPI verwenden, aktivieren Sie es in der Kundenadministration mit diesen Schritten:

1. Melden Sie sich in der Kundenadministration ⧉.
2. Wählen Sie im oberen Menü My Account Customer.
3. Wählen Sie im linken Menü WAPI interface.
4. Legen Sie die erlaubten IP-Adressen (IPv4 oder IPv6, CIDR wird unterstützt), die Art der Benachrichtigungen, das bevorzugte Protokoll und das Passwort fest.
5. Bestätigen Sie die Einstellungen mit der Schaltfläche Set.

---

Kommunikation und Authentifizierung

Die Kommunikation mit der WAPI-Schnittstelle erfolgt über das HTTPS-Protokoll. Die Daten werden mit der Methode POST im Parameter request im XML- oder JSON-Format übergeben. Die Grundform von Befehl und Antwort ist für alle Befehle gleich. Die Datenkodierung ist UTF-8.

URL-Adressen der Schnittstelle:

• XML: https://api.wedos.com/wapi/xml
• JSON: https://api.wedos.com/wapi/json

Aufbau der Anfrage

Die Anfrage besteht aus diesen Daten:

• user: Benutzername (E-Mail-Adresse) Ihres Kundenkontos, Pflichtparameter.
• auth: Autorisierungszeichenfolge, Pflichtparameter. Es handelt sich um den sha1-Hash einer Zeichenfolge, die sich aus dem Benutzernamen, dem sha1-Hash des WAPI-Passworts und der aktuellen Stunde (00-23) zusammensetzt. Die Zeitzone ist Europe/Prague (Winterzeit UTC+1 MEZ, Sommerzeit UTC+2 MESZ). Ein konkretes Beispiel finden Sie im Code unten.
• command: Der eigentliche WAPI-Befehl. Pflichtparameter.
• clTRID: ID der Anfrage, optionaler Parameter. In dieses Element können Sie eine beliebige Zeichenfolge als Kennung einfügen, die WAPI in der Antwort zurückgibt.
• data: Datenteil des Befehls. Optionaler Parameter.
• test: Kennzeichen des Testmodus, optionaler Parameter. Wenn Sie in den Befehl das Element test mit dem Wert 1 einfügen, prüft WAPI Ihren Befehl nur, führt aber keine Änderungen durch.

Die Vorlage der Anfrage (JSON) lautet also:

{
  "request":
  {
    "user": "ihr@login.tld",
    "auth": "Autorisierungszeichenfolge",
    "command": "Name der Anfrage",
    "data":
    {
      Daten der Anfrage
    }
    "clTRID": "Kennung der Anfrage (optional)",
    "test": "1 (wenn Sie die Anfrage nur testen möchten, optional)"
  }
}

Ein vollständiges Anwendungsbeispiel in PHP (Datenformat JSON) kann dann so aussehen:

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'ihr@login.tld'; 
$wpass = 'Ihr WAPI-Passwort'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'Name der Anfrage',
  'data' => ['Array mit den Daten der Anfrage'],
  'clTRID' => 'Kennung der Anfrage (optional)',
  'test' => '1 (wenn Sie die Anfrage nur testen möchten)'
  ]
];

$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);
?>

Aufbau der Antwort

Die Antwort besteht aus diesen Daten:

• code: Rückgabewert des Befehls. Weitere Informationen finden Sie im Kapitel Rückgabecodes.
• result: Textbeschreibung des Rückgabecodes.
• timestamp: Zeitpunkt der Ausführung des Befehls im UNIX-Format.
• clTRID: Kennung des Befehls auf Seiten des Clients.
• svTRID: Kennung des Befehls auf Seiten des Servers.
• command: WAPI-Befehl.
• data: Rückgabewerte. Wenn der Befehl fehlschlägt, werden keine Daten zurückgegeben.
• test: Wird in die Antwort auf Befehle eingefügt, die ebenfalls dieses Kennzeichen enthalten.

Eine Beispielantwort im JSON-Format sieht zum Beispiel so aus:

{
  "response":
  {
    "code": "1000",
    "result": "ok",
    "timestamp": "1286356644",
    "svTRID": "1286356644.0246.21616",
    "command": "domain-create",
    "data": 		
    {
      "num": "1311000863",
      "expiration": "2011-10-06"
    },
    "test": "1"
  }
}

Paginierung und Suche in Listen

Listenbefehle domains-list und dns-rows-list haben optionale Parameter für Suche und Paginierung. Wenn Sie diese nicht angeben, gibt die WAPI die Antwort wie bisher zurück, also die gesamte Liste.

Parameter im Teil data der Anfrage:

• search: Gesuchter Text, ohne Beachtung der Groß- und Kleinschreibung. Bei domains-list wird im Domainnamen gesucht, bei dns-rows-list im Namen oder in den Daten des Eintrags.
• page: Seitennummer ab 1. Der Standardwert ist 1.
• page_limit: Anzahl der Einträge pro Seite, höchstens 1000 (einen größeren Wert reduziert die WAPI auf 1000). Wenn Sie ihn nicht angeben oder 0 angeben, gibt die WAPI alle Einträge zurück.

Befehl dns-rows-list hat zusätzlich diese Filter:

• row_name: Exakter Name des Eintrags. Der Wert @ steht für einen Eintrag direkt auf der Domain.
• rdtype: Typ des Eintrags (A, AAAA, MX, TXT …), die Groß- und Kleinschreibung spielt keine Rolle.

Wenn Sie einen dieser Parameter angeben, gibt die WAPI die Liste als Array zurück (bei domains-list im Element domain, bei dns-rows-list im Element row) und ergänzt im Teil data der Antwort:

• total: Gesamtzahl der Einträge nach Anwendung der Filter.
• page: Nummer der zurückgegebenen Seite.
• page_limit: Verwendete Anzahl der Einträge pro Seite (0 bedeutet alle).

Worauf Sie achten sollten:

• Eine Seite hinter dem Listenende liefert eine leere Liste mit dem Element total, keinen Fehler.
• Einen ungültigen Wert für page oder page_limit (Text, negative Zahl) lehnt die WAPI nicht ab, sondern ersetzt ihn durch den Standardwert: page 1, page_limit 0, also alle Einträge.
• Ein Array anstelle eines Werts in page oder page_limit gibt den Fehler 2101 zurück.
• Befehl dns-domains-list gibt total (als String), page und page_limit immer zurück. Wenn Sie page_limit nicht angeben oder 0 angeben, wird 1000 verwendet.

JSON-Befehl domains-list (aktive Domains, die „example“ enthalten, erste Seite mit zwei Domains), ausführliche Beschreibung in der Dokumentation des Befehls domains-list ⧉:

{
  "request": {
    "user": "ihr@login.tld",
    "auth": "generierte Autorisierungszeichenfolge",
    "command": "domains-list",
    "clTRID": "eigener ID-Code",
    "data": {
      "status": "active",
      "search": "example",
      "page": 1,
      "page_limit": 2
    }
  }
}

JSON-Befehl dns-rows-list (A-Einträge der Domain example.cz, erste Seite mit 50 Einträgen), ausführliche Beschreibung in der Dokumentation des Befehls dns-rows-list ⧉:

{
  "request": {
    "user": "ihr@login.tld",
    "auth": "generierte Autorisierungszeichenfolge",
    "command": "dns-rows-list",
    "clTRID": "eigener ID-Code",
    "data": {
      "domain": "example.cz",
      "rdtype": "A",
      "page": 1,
      "page_limit": 50
    }
  }
}

Benachrichtigung

Asynchrone Operationen 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 eine Operation nicht sofort abschließen kann, gibt es in der Antwort Request pending (1001)zurück. Nach Abschluss der Operation (bei komplexeren Aktionen der einzelnen Schritte) erstellt es eine Benachrichtigung, die einer klassischen Antwort entspricht. Die Benachrichtigung können Sie der zugehörigen Anfrage anhand der Parameter clTRID oder svTRID zuordnen.

Die Daten der Benachrichtigung sind immer in der Kodierung UTF-8.

Benachrichtigungen können Sie auf folgende Weise erhalten (je nach Einstellung bei der Aktivierung):

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

Eine Beispielbenachrichtigung im JSON-Format sieht zum Beispiel so aus:

{
  "notify": {
    "code": 1000,
    "result": "OK",
    "timestamp": 1286957932,
    "clTRID": "AvrX87Kqk6h3",
    "svTRID": "1286957874.1271.15706",
    "command": "ping-async",
    "ID": 2691
  }
}

Systembenachrichtigungen

Systembenachrichtigungen senden Informationen über relevante Ereignisse, derzeit nur über den Transfer einer Domain zu einem anderen Anbieter. Ist für Ihr Konto WAPI aktiv, sendet das System eine solche Information per Benachrichtigung ähnlich wie bei einem asynchronen Befehl.

Das Protokoll, in dem WAPI Systembenachrichtigungen sendet, stellen Sie gemäß dem Kapitel WAPI in der Kundenadministration aktivierenein. Diese Option gilt für Benachrichtigungen, die an eine E-Mail-Adresse oder URL-Adresse gesendet werden. Beim Abrufen aus der POLL-Warteschlange hat die Antwort dieselbe Form wie bei einem Befehl.

Die Struktur ist dieselbe wie bei der klassischen Benachrichtigung, der Befehl (command) lautet immer system-notify. Im Knoten data finden Sie dann ausführlichere Informationen.

---

Grundbefehle

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

ping

Der Befehl ping dient zum Testen der Funktionsfähigkeit von WAPI – zum Beispiel der Zugangsdaten, der IP-Adresse oder des Codes.

Die Rückgabewerte sind:

• 1000 – OK

JSON-Befehl:

{
  "request": {
    "user": "ihr@login.tld",
    "auth": "generierte Autorisierungszeichenfolge",
    "command": "ping",
    "clTRID": "eigener ID-Code"
  }
}

JSON-Antwort:

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "UTF-Zeit",
    "clTRID": "eigener ID-Code",
    "svTRID": "ID-Code des Servers",
    "command": "ping"
  }
}

ping-async

Der Befehl ping-async testet die Funktionsfähigkeit der WAPI-Benachrichtigungen.

Die Rückgabewerte sind:

• 1000 OK
• 1001 Warten auf Befehl

JSON-Befehl:

{
  "request": {
    "user": "ihr@login.tld",
    "auth": "generierte Autorisierungszeichenfolge",
    "command": "ping",
    "clTRID": "eigener ID-Code"
  }
}

JSON-Antwort:

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "UTF-Zeit",
    "clTRID": "eigener ID-Code",
    "svTRID": "ID-Code des Servers",
    "command": "ping"
  }
}

JSON-Benachrichtigung:

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF-Zeit",
    "clTRID": "eigener ID-Code",
    "svTRID": "ID-Code des Servers",
    "command": "ping-async",
    "id": "ID für die POLL-Warteschlange",
    "data": {
      "round": "Versuchsnummer",
      "time": "Zeit",
      "done": 1
    }
  }
}

poll-req und poll-ack

Benachrichtigungen aus der POLL-Warteschlange rufen Sie mit einer Kombination der Befehle poll-req und poll-ack ab: 

1. Mit dem Befehl poll-req laden Sie die älteste verfügbare Benachrichtigung herunter.
2. Mit dem Befehl poll-ack markieren Sie die Benachrichtigung als empfangen und machen damit die nächstneueren verfügbar, bis die Warteschlange leer ist.

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

• 1000 – Benachrichtigung abgerufen
• 1003 – in der Warteschlange befindet sich keine ungelesene Benachrichtigung
• 2150 – für Ihr Konto ist der Abruf von Benachrichtigungen aus der POLL-Warteschlange nicht eingerichtet

JSON-Befehl poll-req:

{
  "request": {
    "user": "ihr@login.tld",
    "auth": "generierte Autorisierungszeichenfolge",
    "command": "poll-req",
    "clTRID": "eigener ID-Code"
  }
}

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

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF-Zeit",
    "clTRID": "eigener ID-Code",
    "svTRID": "ID-Code des Servers",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "UTF-Zeit",
        "clTRID": "eigener ID-Code des gefundenen Befehls",
        "svTRID": "ID-Code des Servers für den gefundenen Befehl",
        "command": "Name des Befehls",
        "id": "ID in der POLL-Warteschlange"
      }
    }
  }
}

JSON-Antwort auf poll-req (leere Benachrichtigungswarteschlange):

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": “1286962852”,
    "clTRID": "eigener ID-Code",
    "svTRID": "ID-Code des Servers",
    "command": "poll-req"
  }
}

Dem Befehl poll-ack übergeben Sie Daten (Parameter):

• id – ID der aktuellen POLL-Benachrichtigung

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

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

JSON-Befehl poll-ack:

{
  "request": {
    "user": "ihr@login.tld",
    "auth": "generierte Autorisierungszeichenfolge",
    "command": "poll-ack",
    "clTRID": "eigener ID-Code",
    "data": {
      "id": “ID der empfangenen POLL-Benachrichtigung”
    }
  }
}

JSON-Antwort auf poll-ack:

{
  "response": {
    "code": “1002”,
    "result": "Notification acquired",
    "timestamp": "UTF-Zeit",
    "clTRID": "eigener ID-Code",
    "svTRID": "ID-Code des Servers",
    "command": "poll-ack"
  }
}

---

Liste der Rückgabecodes

Die Rückgabecodes in Antworten und Benachrichtigungen helfen Ihnen, den Ablauf und mögliche Fehler von WAPI zu erkennen.

Grundlegende Einteilung der Rückgabecodes:

• 1xxx – der Befehl wurde ordnungsgemäß ausgeführt.
• 2xxx – fehlerhafter Befehl (zum Beispiel fehlende Eingabefelder, deren falsches Format oder falscher Wert).
• 3xxx – Fehler des Zielobjekts – die gewünschte Aktion kann nicht ausgeführt werden, das Objekt befindet sich nicht im richtigen Zustand (zum Beispiel beim Versuch, eine bereits vergebene Domain zu registrieren, …).
• 4xxx – Fehler bei der Ausführung des Befehls (z. B. Nichtverfügbarkeit der Domain-Registry, Kommunikationsfehler u. a.).
• 5xxx – interner Fehler oder Zustand unseres Systems.
• x0xx, x1xx – allgemein.
• x2xx – Domains.
• x3xx – DNS.

Die konkreten Antworten auf einen bestimmten Befehl finden Sie immer in der Dokumentation des jeweiligen Befehls.

---

Glossar

• Asynchroner Befehl: Ein Befehl, der längere Zeit ausgeführt wird und nur eine Meldung über die Annahme zurückgibt; den weiteren Verlauf verfolgen Sie über Benachrichtigungen.
• API: Application Programming Interface. Eine Schnittstelle, die es Ihnen ermöglicht, mit eigenem Code Daten abzurufen oder eine Anwendung eines Drittanbieters zu verwalten.
• Daten: Inhalt einiger Befehle, der detaillierte Einstellungen festlegt. Die Struktur der Daten ergibt sich aus dem jeweiligen Befehl.
• JSON: JavaScript Object Notation. Moderne Methode der Kommunikation mit der API.
• Rückgabecode: Eine Zahl, die die Art der WAPI-Antwort auf einen Befehl kennzeichnet.
• Benachrichtigung: JSON- oder XML-Code mit Meldungen über den Verlauf eines asynchronen Befehls.
• Befehl: Eine Anfrage an WAPI.
• Synchroner Befehl: Ein praktisch sofort ausgeführter Befehl. Er gibt eine vollständige Antwort zurück und verwendet keine Benachrichtigungen.
• Systembenachrichtigungen: Eine spezielle Art von Benachrichtigungen über Ereignisse im System, die WAPI automatisch im eingestellten Format sendet.
• UTF-8: Unicode Transformation Format. Ein weit verbreiteter internationaler Standard zur Zeichenkodierung, der eine große Anzahl von Schriftsystemen unterstützt.
• WAPI: Schnittstelle zur Verwaltung einiger Bereiche der Kundenadministration (Guthabenkonto, Domains, DNS).
• XML: eXtended Markup Language. Ältere Methode der Kommunikation mit der API.

War dieser Artikel hilfreich?

Ihr Feedback hilft uns, unsere Artikel zu verbessern.

JaNein

Möchten Sie uns etwas zu diesem Artikel mitteilen? (optional)

Ihre Nachricht geht an das Dokumentationsteam, das sie nicht beantwortet. Wenn Sie Hilfe benötigen, nutzen Sie bitte unser Kontaktformular. Bitte geben Sie hier keine Passwörter oder personenbezogenen Daten an.

Lassen Sie dieses Feld leer