REST API – Handbuch

In diesem Artikel erfahren Sie:

• Wie die WEDOS REST API funktioniert
• Welche Endpoints verfügbar sind
• Wie Sie API-Clients verwalten
• Wie die Protokollierung von API-Anfragen funktioniert
• Häufig gestellte Fragen

---

Funktionen der WEDOS REST API

HTTP REST API v2 ermöglicht die Verwaltung Ihrer WEDOS Dienste aus eigenen Anwendungen und Skripten. Die gesamte Kommunikation läuft über HTTPS unter der Adresse https://api.wedos.com, die Daten werden im JSON-Format gesendet und zurückgegeben.

Um API-Zugriff zu erhalten, müssen Sie einen API-Client mit Zugriffsberechtigungen (Lesen und Schreiben oder nur Lesen – siehe Kapitel Client-Verwaltung ) für einen oder mehrere Endpoints anlegen (siehe Endpoints). Jede Anfrage wird protokolliert (siehe Protokollierung von Anfragen).

Limit für Anfragen

• Das Standardlimit beträgt 1.000 Anfragen pro Stunde und API-Client. Jeder Client hat sein eigenes Limit, das über alle API hinweg geteilt wird (domains, wdns, wgp, …).
• Alle Anfragen zählen auf das Limit, auch abgelehnte.
• Das aktuelle Limit wird in der Client-Liste in der Administration angezeigt.
• Wenn Ihnen das Limit nicht ausreicht, wenden Sie sich an den Kundensupport über das Formular ⧉. Geben Sie das gewünschte Limit und eine Begründung an, warum Sie es setzen möchten. Für Ihr Konto können wir es individuell erhöhen.

HTTP REST API vs. WAPI

WEDOS bietet zwei API an: die ältere WAPI und die neuere HTTP REST API v2. Vergleichen können Sie sie anhand der folgenden Tabelle:

	WAPI	HTTP REST API v2
Authentifizierung	Ein Login und ein WAPI-Passwort für das gesamte Konto	Ein separater API-Client mit eigenem Token für jede Anwendung oder Person
Zugriffsbeschränkungen	Eine verpflichtende Liste von IP-Adressen für das gesamte Konto	Berechtigungs-Scopes, „Nur lesen“, IP-Adressen und Token-Gültigkeit, pro Client festgelegt
Format	XML oder JSON, ein einziger Endpoint, Befehle im Request-Body	REST (HTTP-Methoden und URLs), JSON
Abdeckung	Eine breite Palette von Befehlen für WEDOS Dienste	Domains, Kontakte, NSSETs, WEDOS DNS, WEDOS Global Protection
Log	Ein Log für das gesamte Konto	Ein Log, das den API-Client identifiziert

Wir empfehlen:

• HTTP REST API v2 für neue Integrationen, sofern sie die benötigten Operationen abdeckt, und überall dort, wo Sie den Zugriff einzelner Personen oder Systeme trennen, auf reinen Lesezugriff beschränken oder nachvollziehen müssen, wer was getan hat (Audit, DORA).
• WAPI für Operationen, die HTTP REST API v2 noch nicht anbietet.

Wenn Sie von WAPI zur WEDOS REST API wechseln möchten, gehen Sie wie folgt vor:

1. Legen Sie in der Administration für jede Anwendung oder jedes System einen API-Client mit den erforderlichen Berechtigungs-Scopes an. Eine Anleitung finden Sie im Kapitel Client-Verwaltung .
2. Ersetzen Sie die Aufrufe der WAPI-Befehle durch die entsprechenden Endpoints aus der Dokumentation der jeweiligen API. Siehe Kapitel Endpoints .
3. Die Ergebniscodes der Operationen (zum Beispiel 1000 OK, 3201 Domain ist bereits registriert) sind dieselben wie bei WAPI, da HTTP REST API v2 dieselben Operationen ausführt. Darüber hinaus gibt es allgemeine Codes der REST-Schicht (zum Beispiel 2000 fehlender oder ungültiger Token, 2012 Client nur mit Leserechten), die in der Dokumentation der jeweiligen API beschrieben sind.
4. Während des Übergangs können Sie beide API parallel verwenden.

---

Endpoints

Die WEDOS REST API ermöglicht die Automatisierung der Steuerung folgender Bereiche:

• Domains: Die /domains/ Endpoints übernehmen die Registrierung, Transfers und Verlängerungen von Domains. Sie können außerdem AUTH-IDs versenden sowie DNS-Server/NSSET und KEYSET für DNSSEC einrichten. Ihr Berechtigungs-Scope ist domains. Weitere Informationen finden Sie im Artikel REST API – Domains .
• Domain-Kontakte: Die /contacts/ Endpoints erstellen und verwalten Domain-Kontakte. Transfers sind für .cz-Domains verfügbar. Ihr Berechtigungs-Scope ist domains. Weitere Informationen finden Sie im Artikel REST API – Domain-Kontakte .
• NSSETs: Die /nssets/ Endpoints erstellen und verwalten die NSSET-Objekte von CZ.NIC. Ihr Berechtigungs-Scope ist domains. Weitere Informationen finden Sie im Artikel REST API – Domain-NSSETs .
• DNS: Der /dns/ Endpoint erstellt und verwaltet DNS-Domains sowie einzelne Records. Dazu gehören Importe in den primären DNS und AXFR für den sekundären DNS. Ihr Berechtigungs-Scope ist dns. Weitere Informationen finden Sie im Artikel REST API – DNS .
• WEDOS.protection: Der /wgp/ Endpoints erstellen und verwalten WEDOS.protection-Dienste. Ihr Berechtigungs-Scope ist wgp. Weitere Informationen finden Sie in den Artikeln REST API – WGP Domains, REST API – WGP Services und REST API – WGP Members.

---

Client-Verwaltung

Den API-Zugriff richten Sie in der Kundenadministration im Abschnitt HTTP REST API ein. Erstellen Sie einen eigenen API-Client für jede Anwendung, jedes System oder jede Person. Für jeden Client legen Sie fest:

• Berechtigungs-Scopes: auf welche API der Client zugreifen darf,
• Nur lesen: Der Client kann Informationen nur anzeigen (siehe unten),
• IP-Adressfilterung: erlaubte oder gesperrte IP-Adressen, von denen der Client die API aufrufen darf,
• Token-Gültigkeit: wann der Access Token gültig wird und wann er abläuft.

Der Client authentifiziert sich mit einem Access Token im Header Authorization: Bearer <TOKEN> . Den Token können Sie direkt in der Administration erzeugen, oder Ihre Anwendung fordert ihn selbst mit der Client-ID und dem Client Secret an (siehe Kapitel OAuth2 ).

Einen neuen Client anlegen

Einen neuen Client können Sie nur in der Kundenadministration anlegen. Gehen Sie wie folgt vor:

1. Melden Sie sich in der Kundenadministration an.
2. Navigieren Sie zur Schnittstelle WEDOS REST API (derzeit nicht verfügbar).
3. Klicken Sie auf die Schaltfläche Neuer Client .
4. Geben Sie einen Client-Namen (eine kurze Bezeichnung, die den Client in der Liste identifiziert) ein und wählen Sie im Menü Berechtigungen auswählen einen oder mehrere Berechtigungsbereiche aus. Die verfügbaren Bereiche entsprechen den Endpoints.
5. Optional nehmen Sie weitere Einstellungen vor:
   • Aktivieren Sie den Zugriff Nur lesen . Der Client kann dann Informationen nur abrufen. Anfragen, die Einträge hinzufügen, ändern oder löschen, werden blockiert.
   • Im Abschnitt Token-Gültigkeitwählen Sie aus, wie lange der Token nach seiner Ausstellung gültig bleibt: Keine Ablaufzeit, 7 Tage, 30 Tage, 90 Tage, 1 Jahr oder Benutzerdefiniert. Die Felder Gültig ab und Ablauf zeigen die daraus resultierenden Daten an.
   • Im Abschnitt Sicherheitsbeschränkungenkönnen Sie optional die IP-Adressfilterung aktivieren und eine erlaubte IP-Adresse eingeben. Für weitere Adressen klicken Sie auf + Weitere hinzufügen , oder auf × um eine Adresse zu entfernen. Bei aktivierter Filterung akzeptiert die API nur Anfragen von den aufgeführten Adressen.

Nach Abschluss der Einrichtung bestätigen Sie diese mit der Schaltfläche Client erstellen .

Der neue Client erscheint in der Liste mit seinem Namen, den Berechtigungen, der Zugriffsart (zum Beispiel Lesen, Schreiben), den Gültigkeitsdaten und dem Status. Die Liste können Sie filtern nach Berechtigungen, Status, Gültigkeit und Zugriff.

Client Secret

Direkt nach dem Anlegen eines Clients erscheint der Dialog Geheimer Client-Schlüssel mit der Meldung Kopieren Sie den geheimen Schlüssel und bewahren Sie ihn an einem sicheren Ort auf.

1. Klicken Sie neben dem geheimen Schlüssel auf Kopieren .
2. Bewahren Sie das Secret an einem sicheren Ort auf, zum Beispiel in einem Passwortmanager oder im Secret Store Ihres Servers.
3. Klicken Sie auf Ich habe verstanden, schließen.

Das Secret wird nur in diesem Dialog angezeigt, speichern Sie es also, bevor Sie ihn schließen. Zusammen mit der Client-ID benötigen Sie es, um Token über die API anzufordern (siehe Kapitel OAuth2).

Einen bestehenden Client verwalten

Um die Seite HTTP REST API Einstellungen eines Clients zu öffnen, klicken Sie in der Liste auf das Bearbeiten-Symbol neben seinem Namen. Sie können alle bei der Einrichtung vorgenommenen Einstellungen bearbeiten, einschließlich Name und Berechtigungen.

Client ID und Client Secret können nicht bearbeitet werden.

Bei der Verwaltung eines bestehenden Clients stehen folgende Bedienelemente zur Verfügung:

• Änderungen speichern: Speichert die Änderungen an den Einstellungen des Clients.
• Deaktivieren: Deaktiviert (sperrt) den Client, ohne ihn zu löschen.
• Löschen: Entfernt den Client dauerhaft.
• Zurück zur HTTP REST API Liste: Kehrt zur Client-Liste zurück.
• Aktualisieren: Lädt die Seite neu.

Bearer Token des Clients

Der Bearer Token dient zur Identifikation des Clients beim Zugriff auf die Endpoints. Das Feld zeigt den aktuellen Access Token des Clients. Klicken Sie auf Kopieren , um ihn zu kopieren.

Um den Token zu ersetzen, klicken Sie auf Neuer Token. Der alte Token funktioniert sofort nicht mehr, aktualisieren Sie daher jede Anwendung, die ihn verwendet.

Der Abschnitt Beispiel (curl) zeigt eine sofort einsetzbare Anfrage mit dem aktuellen Token zu Testzwecken.

OAuth2

Ihre Anwendung kann ihren eigenen Token unter POST https://api.wedos.com/oauth2/token mit der Client-ID und dem Secret anfordern. Jede andere HTTP-Methode gibt einen Fehler zurück.

• Client ID: Klicken Sie in der Oberfläche zur Client-Verwaltungauf Client ID anzeigen , um die Client-ID anzuzeigen, und anschließend auf Kopieren.
• Client Secret: Das Secret ist nur nach dem Anlegen des Kontos verfügbar. Weitere Informationen finden Sie im Kapitel Client Secret .

Verwenden Sie eine von zwei Methoden:

• HTTP Basic (empfohlen): der Header Authorization: Basic <base64(client_id:client_secret)>. curl erstellt ihn für Sie mit -u 'client_id:client_secret'.
• Im Request-Body: die Parameter client_id und client_secret.

Senden Sie die Parameter im Body als application/x-www-form-urlencodedoder als JSON mit dem Header Content-Type: application/json.

Parameter	Erforderlich	Beschreibung
grant_type	Ja	Immer client_credentials
scope	Nein	Durch Leerzeichen getrennte Berechtigungs-Scopes aus: domains (umfasst Domain-Kontakte und NSSET), wdns und wgp. Muss eine Teilmenge der Scopes des Clients sein. Wird der Parameter weggelassen, erhält der Token alle Scopes des Clients.
client_id, client_secret	Nur ohne HTTP Basic	Zugangsdaten des Clients

Beispiel: HTTP Basic (empfohlen)

curl -X POST -u '<CLIENT_ID>:<CLIENT_SECRET>' \
  -d 'grant_type=client_credentials' \
  -d 'scope=domains' \
  'https://api.wedos.com/oauth2/token'

Beispiel: Zugangsdaten im Request-Body

curl -X POST \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<CLIENT_ID>' \
  -d 'client_secret=<CLIENT_SECRET>' \
  -d 'scope=domains' \
  'https://api.wedos.com/oauth2/token'

Beispiel: JSON

curl -X POST -H 'Content-Type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"<CLIENT_ID>","client_secret":"<CLIENT_SECRET>","scope":"domains"}' \
  'https://api.wedos.com/oauth2/token'

Das Feld code hat den Wert 1000 bei erfolgreicher Ausstellung des Tokens oder 2000 bei einem Fehler der Client-Authentifizierung oder einer ungültigen Anfrage.

Bei Erfolg enthält data Folgendes:

Feld	Beschreibung
access_token	Der Token, gesendet als Authorization: Bearer <TOKEN>
token_type	Token-Typ (Bearer)
expires_in	Gültigkeit in Sekunden (Standard 3600, also 1 Stunde)
scope	Die Scopes, die der Token tatsächlich erhalten hat

{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3d4",
  "data": {
    "access_token": "3f9c2e7a1b...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "domains"
  }
}

Für client_credentialswird kein Refresh Token ausgestellt. Nach Ablauf des Tokens fordern Sie mit demselben Aufruf einen neuen an.

Bei einem Fehler enthält data die Felder status_code (HTTP-Status von OAuth2, z. B. 400 oder 401), error und error_description.

error	Ursache
invalid_client	Ungültige client_id oder client_secret, oder der Client ist gesperrt
invalid_request	grant_type oder ein anderer Pflichtwert fehlt, oder die Methode war nicht POST
unsupported_grant_type	Nicht unterstützter Wert des Parameters grant_type .
invalid_scope	Der angeforderte Scope existiert nicht oder ist dem Client nicht zugewiesen

{
  "code": 2000,
  "msg": "API method error - Bad Request",
  "request_id": "a1b2c3d5",
  "data": {
    "status_code": 400,
    "error": "invalid_client",
    "error_description": "The client credentials are invalid"
  }
}

Senden Sie den Wert von data.access_token im Header Authorization beim Aufruf eines beliebigen v2-Endpoints, der vom Scope des Tokens abgedeckt ist.

Beispiel:

curl -X GET -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/domains'

Beachten Sie die folgenden Best Practices:

• Speichern Sie den Token und verwenden Sie ihn wieder, bis er abläuft (expires_in). Fordern Sie nicht vor jedem API-Aufruf einen neuen Token an.
• Wenn ein v2-Endpoint einen Authentifizierungsfehler zurückgibt (2000), fordern Sie einen neuen Token an und wiederholen Sie den Aufruf.
• Fordern Sie nur die Scopes an, die Ihre Anwendung benötigt, und verwenden Sie Nur lesen für Clients, die niemals Daten ändern.
• Beschränken Sie jeden Client nach Möglichkeit auf bekannte IP-Adressen.
• Legen Sie für jede Anwendung einen eigenen Client an, damit Sie einen davon deaktivieren oder löschen können, ohne die anderen zu beeinträchtigen.

Empfohlene Einrichtung für Teams

Für mehrere Personen mit API-Zugriff empfehlen wir die folgende Einrichtung:

• Ein API-Client pro Person oder System. Das Log zeigt, wer welche Anfrage gestellt hat, und wenn jemand ausscheidet, sperren Sie nur dessen Client.
• Nur die Scopes, die Sie benötigen. Ein Client für DNS benötigt keinen Zugriff auf Domains.
• „Nur lesen“, wo immer es ausreicht – Monitoring, Reports, Statusprüfungen.
• Beschränkung auf die IP-Adressen der Server oder Netze, die die API tatsächlich aufrufen.
• Ablauf des Tokens. Legen Sie eine Gültigkeitsdauer fest und erneuern Sie den Token regelmäßig.
• Das Client Secret ausschließlich serverseitig aufbewahren – niemals in einem Browser, einer mobilen App oder einem öffentlichen Repository.

Wenn jemand ausscheidet:

1. Sperren oder löschen Sie dessen API-Client in der Client-Liste. Alle seine Token funktionieren sofort nicht mehr, und es kann kein neuer Token dafür angefordert werden. Andere Clients sind davon nicht betroffen.
2. Wenn jemand anderes seine Arbeit übernimmt, sollten Sie für diese Person immer einen neuen Client anlegen .

---

Protokollierung von Anfragen

Der Abschnitt HTTP REST API der Administration enthält ein Log der Anfragen. Sie können es nach Berechtigungs-Scope, API-Client, Status und HTTP-Methode filtern.

Um auf das Log zuzugreifen, gehen Sie wie folgt vor:

1. Melden Sie sich in der Kundenadministration an.
2. Navigieren Sie zur Schnittstelle WEDOS REST API (derzeit nicht verfügbar).
3. Klicken Sie auf die Schaltfläche Anfragelog der HTTP REST API anzeigen .

Jeder Client in der Liste hat zusätzlich den Link Log , der das auf die Anfragen dieses Clients gefilterte Log öffnet.

Zu jeder Anfrage erfassen wir:

• Datum und Uhrzeit sowie die IP-Adresse, von der die Anfrage kam,
• den API-Client (ID und Name) und den Berechtigungs-Scope,
• HTTP-Methode, URL und den ausgeführten Befehl,
• die Eingabedaten und die Antwort der API (Ergebnis und Rückgabecode).

Wir erfassen nicht:

• den Access Token oder das Client Secret – der Header Authorization wird nicht im Anfragelog gespeichert, und der Token ist in den internen Aufzeichnungen von WEDOS maskiert,
• sensible Werte in den Eingabedaten (Passwörter und Ähnliches) werden maskiert gespeichert.

Weitere wichtige Informationen:

• Die Eingabedaten und die Antwort werden zusammen bis zu 1.024 Zeichen gespeichert. Alles darüber hinaus wird abgeschnitten.
• Die Aufzeichnungen werden 90 Tageaufbewahrt und danach automatisch gelöscht.
• Das Log kann noch nicht exportiert oder über die API ausgelesen werden. Es ist nur in der Kundenadministration verfügbar.

---

Häufig gestellte Fragen