API Syntax

Unveränderte API-Syntax

Trotz neuer DNS API Zugänge und -Funktionen bleibt die API-Syntax unverändert zu vorherigen Versionen. Bestehende Integrationen und Skripte, die die DNS API nutzen, funktionieren weiterhin ohne Anpassungen (außer den neuen Logins).

Einführung¶

Servercow bietet für alle Domain-Kunden eine eigene API-Schnittstelle an, welche du nutzen kannst, 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 du mit der API ansprechen möchtest.

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 erhältst du im JSON-Format.

Verfügbare Record-Typen

Die API unterstützt folgende Typen: A, AAAA, CNAME, TXT, MX, CAA, TLSA, SRV, SSHFP, SMIMEA, HTTPS und SVCB.

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-, TLSA-, HTTPS- und SVCB-Records

Da TXT-, CAA-, TLSA-, HTTPS- und SVCB-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.

Hinweis für HTTPS- und SVCB-Records

HTTPS- und SVCB-Records (RFC 9460) werden im Format Priorität Ziel [Parameter=Wert ...] angegeben. Sie werden z.B. benötigt, um HTTP/3 anzukündigen oder Encrypted Client Hello (ECH) zu nutzen.

{
  "type": "HTTPS",
  "name": "www",
  "content": "1 . alpn=h2,h3 ech=AEn+DQBF...",
  "ttl": 300
}

Priorität: 1 bis 65535 für normale Einträge. 0 ist der Alias-Modus und verweist nur auf einen anderen Hostnamen, z.B. 0 svc.example.net (ohne Parameter).
Ziel: . steht für den Namen des Records selbst, alternativ ein anderer Hostname.
Parameter: alpn, no-default-alpn, port, ipv4hint, ipv6hint, ech, mandatory sowie key7 bis key65534.
Für portspezifische Einträge sind Namen wie _8443._https.www möglich.

Die API bringt den Inhalt beim Speichern in eine einheitliche Schreibweise (Parameter nach Schlüssel sortiert, ech in Anführungszeichen). Beim Auslesen erhältst du z.B. 1 . alpn=h2,h3 ech="AEn+DQBF...". Diesen Wert kannst du unverändert wieder an die API senden.

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 1 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"
}