Core concepts

The reference describes every endpoint on its own, and in doing so assumes you know what it is talking about. This page fills that in: the ten terms people otherwise trip over twice.

Domain, zone, record

Three levels that are easy to mix up:

The domain is what you registered — example.de. It is a contract with a registry, and the term, the owner and the nameservers hang off it.

The zone is the DNS data belonging to that domain: the collection of all records your nameservers are responsible for. It lives at regfish as soon as the domain is managed there — but it only takes effect once the domain is delegated, more on that below.

A record is a single entry within it: “www.example.de. points to 203.0.113.10”. Records have a type, a name, data and a TTL.

In practice that means: GET /dns/zones lists zones, GET /dns/{domain}/rr the records inside them.

The dot at the end

Names in DNS are fully qualified — they end with a dot: www.example.de. The dot stands for the root of the name hierarchy.

The regfish API takes that seriously: the name field requires a name with a trailing dot, otherwise it rejects the request. In the interface you may leave it off; it is added for you there.

The rrid

Every record has a number, the rrid (resource record ID). It identifies exactly this one entry.

That matters because name and type are not unique: a domain can have several TXT records at the same name, and several MX records anyway. To change or delete one particular record, you need the rrid.

You get it from the response of GET /dns/{domain}/rr — the field is called id there. With it you can then use PATCH /dns/rr/{rrid} and DELETE /dns/rr/{rrid}.

TTL — and why the order matters

The TTL (time to live) tells resolvers how long they may cache a response. Allowed values are 60 to 604800 seconds, so one minute to one week.

The thing everyone gets wrong once: when you move an address, it is not the new TTL that counts but the old one. Resolvers hold on to the previous response for as long as the TTL that applied when they fetched it allowed.

So if you want to move on Tuesday, you lower the TTL to 300 on Monday — and only change the address after that. The other way round achieves nothing.

Record types

Type	Used for	Data
`A`	Web server over IPv4	IPv4 address
`AAAA`	Web server over IPv6	IPv6 address
`CNAME`	Pointing to another name	Target name
`ALIAS`	like `CNAME`, but also allowed on the domain itself	Target name
`MX`	Mail server	Target name + priority
`TXT`	free text: SPF, DKIM, DMARC, verifications	Text
`CAA`	which certificate authority may issue	Flags, tag, value

Why ALIAS exists at all: a CNAME cannot coexist with other records at the same name. At the domain itself (example.de.) there must always be SOA and NS records — so a CNAME is ruled out there. ALIAS behaves like a CNAME from the outside, but is resolved by the nameservers, which lets it sit at the root.

Delegation: who is responsible for the zone

A zone only takes effect once the registry knows that it is the one to be asked. That assignment is called delegation, and it lives at the registry, not in the zone itself.

For as long as example.de still points at the old provider’s nameservers, you can create as many records at regfish as you like — the world will not see them. Only the nameserver change (PUT /domains/{domain}/nameservers or in the dash) switches that over.

That is why the DNS Doctor checks the delegation first: almost everything that comes in as “it does not work” hangs on it.

DNSSEC runs asynchronously

DNSSEC signs the answers from your zone. For that to work, a key reference (DS record) has to be lodged with the registry — and the registry does not work instantly.

The API models this with two fields:

desired_state — the state you want
live_state — the state the registry and the delegation check actually show

The two are allowed to differ for a while. That is not an error, it is the normal case during a transition. To wait for completion, do not poll the status in a tight loop — query the job list instead: GET /dns/{domain}/dnssec/jobs.

TLS: order, certificate, DCV

With certificates there are three things to keep apart:

The order is the process at the certificate authority. It can outlive a single certificate — a reissue continues under the same order.

The certificate is what ends up on your server.

DCV (domain control validation) is the proof that the domain is yours. regfish does this through a DNS entry: a CNAME with a token is created, the certificate authority queries it, and the certificate is issued afterwards. If the zone runs at regfish, this happens automatically.

One peculiarity with organization-validated products (OV): there the API can answer with action_required and pass along a completion_url. The order has been created in that case, but is waiting for a step that a human has to carry out in the dash. The procedure is described in the recipe Order an OV certificate.

How responses are structured

All JSON responses from the API carry the same envelope:

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

success says whether the call went through, code carries the status, and the actual data sits under response. In the error case success is false and a message stands there instead of response.

In practice that means: the HTTP status alone is not enough. Always check success as well.

Permissions

An API key carries permissions, and every endpoint requires one of them:

Permission	Allows
`domain:read`	Reading domains and nameservers
`domain:write`	Changing nameservers, requesting AuthInfo
`dns:read`	Reading zones, records and DNSSEC status
`dns:write`	Creating, changing and deleting records; managing DNSSEC
`hosting:read`	Reading hosting packages, aliases and databases

The names tls:read, tls:write, hosting:write, email:read and email:write are reserved but not yet bound to any endpoint. A key with full product access holds all of them — for a script that only reads, that is more than it needs.

Which permissions an existing key has is revealed by GET /meta/token. If one is missing, the API rejects the call and names the missing permission in its error message.