Grundbegriffe

Die Referenz beschreibt jeden Endpunkt einzeln und setzt dabei voraus, dass du weißt, wovon sie redet. Diese Seite holt das nach: die zehn Begriffe, über die man sonst zweimal stolpert.

Domain, Zone, Record

Drei Ebenen, die leicht durcheinandergehen:

Die Domain ist das, was du registriert hast — example.de. Sie ist ein Vertrag mit einer Registry, und an ihr hängen Laufzeit, Inhaber und Nameserver.

Die Zone ist der DNS-Datenbestand zu dieser Domain: die Sammlung aller Einträge, für die deine Nameserver zuständig sind. Sie liegt bei regfish, sobald die Domain dort verwaltet wird — wirksam wird sie aber erst mit der Delegierung, dazu unten mehr.

Ein Record ist ein einzelner Eintrag darin: „www.example.de. zeigt auf 203.0.113.10”. Records haben einen Typ, einen Namen, Daten und eine TTL.

Praktisch heißt das: GET /dns/zones listet Zonen, GET /dns/{domain}/rr die Records darin.

Der Punkt am Ende

Namen im DNS sind vollständig qualifiziert — sie enden mit einem Punkt: www.example.de. Der Punkt steht für die Wurzel der Namenshierarchie.

Die regfish-API nimmt das ernst: Das Feld name verlangt einen Namen mit abschließendem Punkt, sonst weist sie die Anfrage ab. In der Oberfläche darfst du ihn weglassen, dort wird er ergänzt.

Tipp

Wenn ein POST /dns/rr mit 400 antwortet und du den Fehler nicht findest — prüf zuerst den Punkt am Ende.

Die rrid

Jeder Record hat eine Nummer, die rrid (Resource Record ID). Sie identifiziert genau diesen einen Eintrag.

Das ist wichtig, weil Name und Typ nicht eindeutig sind: Eine Domain kann mehrere TXT-Records am selben Namen haben, mehrere MX sowieso. Wer einen bestimmten davon ändern oder löschen will, braucht die rrid.

Du bekommst sie aus der Antwort von GET /dns/{domain}/rr — dort heißt das Feld id. Damit gehen dann PATCH /dns/rr/{rrid} und DELETE /dns/rr/{rrid}.

TTL — und warum die Reihenfolge zählt

Die TTL (Time To Live) sagt Resolvern, wie lange sie eine Antwort zwischenspeichern dürfen. Erlaubt sind 60 bis 604800 Sekunden, also eine Minute bis eine Woche.

Der Punkt, den man einmal falsch macht: Beim Umzug einer Adresse zählt nicht die neue TTL, sondern die alte. Resolver halten die bisherige Antwort so lange, wie es die TTL erlaubte, die beim Abruf galt.

Wer also am Dienstag umziehen will, senkt am Montag die TTL auf 300 — und ändert erst danach die Adresse. Umgekehrt bringt es nichts.

Record-Typen

Typ	Wofür	Daten
A	Webserver über IPv4	IPv4-Adresse
AAAA	Webserver über IPv6	IPv6-Adresse
CNAME	Verweis auf einen anderen Namen	Zielname
ALIAS	wie CNAME, aber auch auf der Domain selbst erlaubt	Zielname
MX	Mailserver	Zielname + Priorität
TXT	freier Text: SPF, DKIM, DMARC, Verifizierungen	Text
CAA	welche Zertifizierungsstelle ausstellen darf	Flags, Tag, Wert

Warum es ALIAS überhaupt gibt: Ein CNAME verträgt sich nicht mit anderen Records am selben Namen. An der Domain selbst (example.de.) stehen aber zwingend SOA und NS — dort ist ein CNAME deshalb ausgeschlossen. ALIAS verhält sich nach außen wie ein CNAME, wird aber von den Nameservern aufgelöst und darf so auch an der Wurzel stehen.

Delegierung: wer für die Zone zuständig ist

Eine Zone wirkt erst, wenn die Registry weiß, dass sie gefragt werden soll. Diese Zuweisung heißt Delegierung, und sie steht bei der Registry, nicht in der Zone selbst.

Solange example.de noch auf die Nameserver des alten Anbieters zeigt, kannst du bei regfish Records anlegen, so viele du willst — die Welt sieht sie nicht. Erst der Nameserver-Wechsel (PUT /domains/{domain}/nameservers oder im dash) schaltet um.

Deshalb prüft der DNS-Doctor als Erstes die Delegierung: Fast alles, was „geht nicht” heißt, hängt daran.

DNSSEC läuft asynchron

DNSSEC signiert die Antworten deiner Zone. Damit das funktioniert, muss ein Schlüsselverweis (DS-Record) bei der Registry hinterlegt sein — und die arbeitet nicht sofort.

Die API bildet das mit zwei Feldern ab:

• desired_state — der Zustand, den du willst
• live_state — der Zustand, den die Registry und die Delegationsprüfung tatsächlich zeigen

Die beiden dürfen vorübergehend auseinanderlaufen. Das ist kein Fehler, sondern der Normalfall während einer Umstellung. Wer auf den Abschluss warten will, fragt nicht in enger Schleife den Status ab, sondern die Auftragsliste: GET /dns/{domain}/dnssec/jobs.

Achtung

Nameserver wechseln, während DNSSEC aktiv ist, macht die Domain für alle prüfenden Resolver unerreichbar — und das lässt sich nicht schnell zurücknehmen, weil die Registry-Daten nachziehen müssen. Erst DNSSEC beenden, abwarten, dann umstellen.

TLS: Bestellung, Zertifikat, DCV

Bei Zertifikaten sind drei Dinge auseinanderzuhalten:

Die Bestellung ist der Vorgang bei der Zertifizierungsstelle. Sie kann länger leben als ein einzelnes Zertifikat — eine Neuausstellung (Reissue) läuft unter derselben Bestellung weiter.

Das Zertifikat ist das, was am Ende auf deinem Server liegt.

DCV (Domain Control Validation) ist der Nachweis, dass dir die Domain gehört. regfish macht das über einen DNS-Eintrag: Es wird ein CNAME mit einem Token angelegt, die Zertifizierungsstelle fragt ihn ab, und danach wird ausgestellt. Läuft die Zone bei regfish, passiert das automatisch.

Eine Besonderheit bei organisationsvalidierten Produkten (OV): Dort kann die API mit action_required antworten und eine completion_url mitgeben. Die Bestellung ist dann angelegt, wartet aber auf einen Schritt, den ein Mensch im dash erledigen muss. Der Ablauf steht im Rezept OV-Zertifikat bestellen.

Wie Antworten aufgebaut sind

Alle JSON-Antworten der API tragen dieselbe Hülle:

{
  "success": true,
  "code": 200,
  "response": { }
}

success sagt, ob der Aufruf durchging, code trägt den Status, und die eigentlichen Daten stehen unter response. Im Fehlerfall ist success falsch und statt response steht dort eine Meldung.

Praktisch heißt das: Der HTTP-Status allein genügt nicht. Prüf immer auch success.

Rechte

Ein API-Key trägt Rechte, und jeder Endpunkt verlangt eines davon:

Recht	Erlaubt
domain:read	Domains und Nameserver lesen
domain:write	Nameserver ändern, AuthInfo anfordern
dns:read	Zonen, Records und DNSSEC-Status lesen
dns:write	Records anlegen, ändern, löschen; DNSSEC verwalten
hosting:read	Hosting-Pakete, Aliase und Datenbanken lesen

Die Namen tls:read, tls:write, hosting:write, email:read und email:write sind reserviert, aber noch an keinen Endpunkt gebunden. Ein Schlüssel mit vollem Produktzugriff hat alle — für ein Skript, das nur liest, ist das mehr als nötig.

Welche Rechte ein bestehender Schlüssel hat, verrät GET /meta/token. Fehlt eines, weist die API den Aufruf ab und nennt in der Fehlermeldung das fehlende Recht.

Weiterlesen

• Erste Schritte — der erste Aufruf
• API-Key erstellen — Schlüssel anlegen und einschränken
• Rezepte — fertige Abläufe, in denen diese Begriffe zusammenkommen