API Syntax

Einführung¶

Servercow bietet für alle Domain Kunden eine eigene API Schnittstelle an, welche Sie nutzen können, um DNS Einstellungen auch per API Call abzuändern.

Grundsätzlich gilt die folgende URL zum Ansprechen der DNS API:

https://api.servercow.de/dns/v1/domains/example.org

Hinweis

example.org entspricht der Domain, welche Sie mit der API ansprechen möchten.

Die Authentifizierung erfolgt im Header. Ebenso wird hier der Content-Type ausdrücklich als application/json angegeben!

Content-Type: application/json
X-Auth-Username: servercow_username
X-Auth-Password: servercow_password

Die Antwort der API erhalten Sie im JSON-Format.

Vergfügbare Record Typen

Bislang unterstützt die API folgende Typen: TXT, A, AAAA, CNAME, TLSA, CAA und MX - weitere folgen.

Anwendungsbeispiele¶

Beispiel: Auslesen aktiver Records einer Domain via cURL

curl -X GET 'https://api.servercow.de/dns/v1/domains/example.org' \
-H 'X-Auth-Username: servercow_username' \
-H 'X-Auth-Password: servercow_password' \
-H 'Content-Type: application/json'

Im obigen Request verwenden wir die Methode GET. Außer den Headern geben wir keine Daten an die API weiter.

Beispiel: Erstellen und Ändern eines Records in einer Domain via cURL

curl -X POST 'https://api.servercow.de/dns/v1/domains/example.org' \
-H 'X-Auth-Username: servercow_username' \
-H 'X-Auth-Password: servercow_password' \
-H 'Content-Type: application/json' \
--data '{"type":"TXT","name":"_acme-challenge.www","content":"acbdefghijklmnopqrstuvwxyz","ttl":20}'

Im obigen Request verwenden wir die Methode POST. Neben den Header-Feldern benötigt die API nun ein JSON-Datenfeld mit den gewünschten Werten für den neuen DNS-Record - aus obigem Beispiel:

{
"type": "TXT",
"name": "_acme-challenge.www",
"content": "acbdefghijklmnopqrstuvwxyz",
"ttl": 20
}

Hinweis für TXT-, CAA- und TLSA-Records

Da TXT-, CAA- und TLSA-Felder bei gleichem Namen mehrfach mit unterschiedlichem Inhalt existieren können, darf der Parameter "content" ein Array sein!

Beispiel 1: "content": ["zeile1", "zeile2", "zeile3"]
Beispiel 2: --data '{
    "name": "_25._tcp.example",
    "ttl": 120,
    "type": "TLSA",
    "content": [
    "3 1 1 654321",
    "3 1 1 123456"
    ]
}'
Beispiel 3: --data '{
    "name": "",
    "ttl": 120,
    "type": "CAA",
    "content": [
    "0 issue \"symantec.com\"",
    "0 issue \"letsencrypt.org\""
    ]
}'

Der dritte Parameter des CAA-Records sollte wie bei \"letsencrypt.org\" eingeklammert werden.

Die Parameter "type", "name" und "content" sind Pflichtangaben. Die "ttl" Zeitangabe wird in Sekunden angegeben. Dieser beträgt per Standard 120 (also 2 Minuten), kann aber als ein Wert zwischen 0 und 604800 (1 Woche) optional angegeben werden.

Zum Setzen eines Inhaltes für die Hauptdomain (Beispiel: example.org) wir da Feld Name leer gelassen, Beispiel: "name": ""

Achtung

Ist ein DNS-Eintrag bereits vorhanden, wird er überschrieben.

Beispiel: Entfernen eines Records in einer Domain via cURL

curl -X DELETE 'https://api.servercow.de/dns/v1/domains/example.org' \
-H 'X-Auth-Username: servercow_username' \
-H 'X-Auth-Password: servercow_password' \
-H 'Content-Type: application/json' \
--data '{"type":"TXT","name":"_acme-challenge.www"}'

Im obigen Request verwenden wir die Methode DELETE. Neben den Header-Feldern benötigt die API ein JSON-Datenfeld mit den Pflichtangaben "type" und "name", um den entsprechenden Eintrag zu entfernen:

{
    "type": "TXT",
    "name": "_acme-challenge.www"
}