DNS API - Dokumentation

Übersicht

Die DNS API ermöglicht die Verwaltung von DNS-Records über einfache HTTP-Requests. Typische Anwendungsfälle sind die Automatisierung von DNS-Änderungen in Deployment-Pipelines sowie die automatische Erneuerung von TLS-Zertifikaten über das ACME DNS-01 Challenge-Verfahren — kompatibel mit Let's Encrypt und anderen ACME-fähigen CAs.

Tipp: Alle Endpunkte unterstützen den Parameter ?pretty, der die JSON-Antwort lesbar formatiert ausgibt — praktisch zur manuellen Inspektion per curl oder Browser.

Authentifizierung

Alle API-Requests erfordern einen gültigen API-Key im X-API-Key Header:

$ curl -H "X-API-Key: DEIN_API_KEY" https://api.ewetel.de/api/v1/dns/zones/example.com
Hinweise: Pro API-Key können folgende Zugriffsbeschränkungen konfiguriert werden:
  • Domain-Einschränkung: zu verwaltende Domains müssen einem API-Key zugeordnet sein. Ein API-Key kann für den Zugriff auf mehrere Domains berechtigt werden.
  • IP-Einschränkung: optional kann der Zugriff nur von bestimmten Quell-IPs oder Netzwerken (z.B. 203.0.113.10 oder 203.0.113.0/24) erlaubt werden. Wenn eine feste Quell-IP oder ein festes Quell-Netz vorhanden ist empfehlen wir eine entsprechende Einschränkung.

API-Endpunkte

GET /v1/dns/zones/{zone}

Ruft Informationen zu einer DNS-Zone ab.

Beispiel:

$ curl -X GET \
  -H "X-API-Key: DEIN_API_KEY" \
  https://api.ewetel.de/api/v1/dns/zones/example.com?pretty

Erfolgreiche Antwort (200):

{
  "success": true,
  "data": {
    "master": null,
    "name": "example.com",
    "type": "MASTER",
    "record_count": 17,
    "infrastructure": [
      {
        "content": "ans0.ewetel.de hostmaster.ewetel.de 2026043011 40000 7200 604800 86400",
        "id": 240036,
        "name": "example.com",
        "ttl": 86400,
        "type": "SOA"
      },
      {
        "content": "ans0.ewetel.de",
        "id": 240037,
        "name": "example.com",
        "ttl": 86400,
        "type": "NS"
      },
      { ... weitere NS-Records ... }
    ]
  }
}

Fehler (403 - Domain nicht erlaubt):

{
  "success": false,
  "error": "Forbidden",
  "message": "Access to this domain not allowed"
}

GET /v1/dns/zones/{zone}/records

Listet alle DNS-Records einer Zone auf.

Beispiel:

$ curl -X GET \
  -H "X-API-Key: DEIN_API_KEY" \
  https://api.ewetel.de/api/v1/dns/zones/example.com/records?pretty

Erfolgreiche Antwort (200):

{
  "success": true,
  "data": [
    {
      "content": "xyz123",
      "id": 489777,
      "name": "_acme-challenge.example.com",
      "ttl": 3600,
      "type": "TXT"
    },
    {
      "content": "mx-x0.ewetel.de",
      "id": 240042,
      "name": "example.com",
      "prio": 10,
      "ttl": 3600,
      "type": "MX"
    },
    {
      "content": "www.example.com",
      "id": 240929,
      "name": "ein-cname.example.com",
      "ttl": 3600,
      "type": "CNAME"
    },
    {
      "content": "192.0.2.1",
      "id": 240041,
      "name": "www.example.com",
      "ttl": 3600,
      "type": "A"
    },
    {
      "content": "192.0.2.2",
      "id": 489778,
      "name": "www2.example.com",
      "ttl": 3600,
      "type": "A"
    },
    { ... SOA- und NS-Records ... }
  ]
}

POST /v1/dns/zones/{zone}/records

Fügt einen neuen DNS-Record hinzu.

Beispiel - A-Record:

$ curl -X POST \
  -H "X-API-Key: DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"www.example.com","type":"A","content":"192.0.2.1","ttl":3600}' \
  https://api.ewetel.de/api/v1/dns/zones/example.com/records?pretty

Beispiel - TXT-Record (für Let's Encrypt ACME Challenge):

$ curl -X POST \
  -H "X-API-Key: DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"_acme-challenge.example.com","type":"TXT","content":"xyz123","ttl":3600}' \
  https://api.ewetel.de/api/v1/dns/zones/example.com/records?pretty

Pflichtfelder:

Field Type Description
name string Record-Name (z.B. "example.com" oder "_acme-challenge")
type string Record-Type (A, AAAA, CNAME, MX, TXT, etc.)
content string Record-Content (z.B. IP-Address oder Text)

Optionale Felder:

Field Type Standard Description
ttl integer 3600 Time to Live in Sekunden (Minimum: 180)
prio integer 0 Priority (für MX-Records)

Erfolgreiche Antwort (200):

{
  "success": true,
  "data": true
}
TTL: Nach dem Hinzufügen eines Records oder nach einer Änderung eines bestehenden Records kann es einige Minuten dauern, bis die Änderung weltweit wirksam ist. Hier ist vor allem die TTL des Records relevant.
Serial im SOA Record: Nach hinzufügen, ändern oder löschen eines Records muss die SOA Serial der Zone nicht aktualisiert werden. Die Serial wird automatisch im Backend aktualisiert.

DELETE /v1/dns/zones/{zone}/records/{id}

Löscht einen DNS-Record anhand seiner ID.

Beispiel:

$ curl -X DELETE \
  -H "X-API-Key: DEIN_API_KEY" \
  https://api.ewetel.de/api/v1/dns/zones/example.com/records/12345

Erfolgreiche Antwort (200):

{
  "success": true,
  "message": "Record deleted successfully"
}

HTTP Status Codes

Code Meaning Description
200 OK Request erfolgreich / Record erstellt
400 Bad Request Ungültige Anfrage (fehlende Pflichtfelder)
401 Unauthorized API-Key fehlt oder ist ungültig
403 Forbidden Kein Zugriff auf diese Domain
404 Not Found Endpoint oder Record nicht gefunden
405 Method Not Allowed HTTP-Methode nicht erlaubt
500 Server Error SOAP-Fehler oder interner Serverfehler