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.

Verfü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:
{
  "name": "_25._tcp.example",
  "ttl": 120,
  "type": "TLSA",
  "content": [
    "3 1 1 654321",
    "3 1 1 123456"
  ]
}

Beispiel 3:
{
  "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) wird das 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"
}