DNS-API

Gebaut Die API läuft unter https://dns.paasbox.com/v1. Tokens werden ausgegeben, sobald der Dienst öffnet, mit der ersten Veröffentlichung der Komponenten. DNS-Namen für deine Cluster erklärt den Dienst; diese Seite ist die Referenz.

Basis-URL und Kompatibilität

https://dns.paasbox.com/v1

Die API bedient die Zonen- und Record-Set-Anfragen der Hetzner-Cloud-API, mit Hetzners Anfrage- und Antwortformaten unverändert: {"zones": […], "meta": {"pagination": …}}, {"rrset": {…}}, {"action": {…}}. Ein Hetzner-Client funktioniert damit, wenn du seinen Endpunkt auf diese URL und sein Token auf ein DNS-Token von PaaSbox setzt. Beim hcloud-CLI und Hetzners Go-Client sind das HCLOUD_ENDPOINT und HCLOUD_TOKEN.

Es gibt eine Zone, paasbox.app. Dein Team schreibt unterhalb von <team>.paasbox.app, und Eintragsnamen sind relativ zur Zone: Das Record-Set api.prod.acme ist api.prod.acme.paasbox.app. Ein Wildcard-Name wird als wörtliches * geschickt, zum Beispiel *.apps.acme.

Authentifizierung

Jede Anfrage trägt ein Team-Token als Bearer-Token:

Authorization: Bearer pbdns_…

Ein Token gehört einem Team, trägt den Scope dns und wird einmal angezeigt, wenn es angelegt wird. Ohne Token oder mit einem unbekannten oder widerrufenen lautet die Antwort 401 unauthorized; mit einem Token ohne den Scope dns 403 forbidden. Ein Team kann bis zu fünf aktive Tokens haben.

Endpunkte

Methode und Pfad	Was er tut
GET /zones	Listet die eine Zone, paasbox.app. ?name= mit einem anderen Namen liefert eine leere Liste.
GET /zones/{zone}	Die Zone, über ihre ID oder ihren Namen.
GET /zones/{zone}/rrsets	Die Record-Sets deines Teams, und nur diese.
POST /zones/{zone}/rrsets	Legt ein Record-Set an: name, type, records (jeder mit einem value und einem optionalen comment), optional ttl und labels.
GET /zones/{zone}/rrsets/{name}/{type}	Ein Record-Set.
DELETE /zones/{zone}/rrsets/{name}/{type}	Löscht ein Record-Set.
POST /zones/{zone}/rrsets/{name}/{type}/actions/set_records	Ersetzt die Einträge eines Record-Sets.
POST /zones/{zone}/rrsets/{name}/{type}/actions/add_records	Fügt einem Record-Set Einträge hinzu.
POST /zones/{zone}/rrsets/{name}/{type}/actions/remove_records	Entfernt Einträge aus einem Record-Set.
POST /zones/{zone}/rrsets/{name}/{type}/actions/change_ttl	Ändert die TTL eines Record-Sets.
GET /actions?id=…, GET /actions/{id}	Der Fortschritt eines Schreibzugriffs, für Clients, die darauf warten. Nur Zonen-Aktionen sind sichtbar.

Listen sind so paginiert, wie Hetzner paginiert: page und per_page (standardmäßig 25, höchstens 50), mit meta.pagination in der Antwort.

Nicht bedient: Zonen anlegen, ändern oder löschen, Zonendateien, der Schutz von Zonen und Record-Sets, die übrigen Record-Set-Aktionen und jede Ressource der Hetzner-Cloud-API, die nicht DNS ist, etwa Server und Volumes. Eine Methode, die die API auf einem Pfad nicht unterstützt, antwortet mit 405 method_not_allowed.

Was ein Token schreiben darf

• Namen: den eigenen Namen deines Teams (acme; ein A-Eintrag auf acme.paasbox.app ist erlaubt) und jeden Namen, der auf .acme endet. Nicht die Zonenspitze, nicht den Namen eines anderen Teams, keinen Namen außerhalb der Zone. Namen müssen einfache DNS-Namen sein; ein Name wird geprüft, bevor er Hetzner erreicht.
• Typen: A, AAAA, CNAME und TXT. NS wird überall abgelehnt.
• Werte: höchstens 50 Einträge pro Record-Set, jeder Wert höchstens 4.096 Zeichen; eine TTL ist leer oder eine nicht negative ganze Zahl.

Das Lesen eines Namens außerhalb deines Teams antwortet mit 404 not_found, nicht 403, damit sich der Inhalt der Zone über die API nicht auflisten lässt. Jeder Schreibzugriff wird im Audit-Log des Teams festgehalten, mit Token, Name, Typ und Hetzners Antwort.

Grenzen

Einträge pro Team	200, gezählt über alle deine Record-Sets
Einträge pro Record-Set	50
Aktive Tokens pro Team	5
Anfragen	In Arbeit 120 pro Minute und Token, 600 pro Minute und Team, 300 pro Minute und Adresse, bevor ein Token geprüft wird

Fehler

Fehler haben Hetzners Form, damit die Fehlerbehandlung eines Clients unverändert bleibt:

{"error": {"code": "resource_limit_exceeded", "message": "this team is limited to 200 DNS records on acme.paasbox.app"}}

Status	code	Wann
400	invalid_input	Der Body ist kein JSON-Objekt, records ist leer oder fehlerhaft, oder ttl ist keine ganze Zahl.
401	unauthorized	Kein Token, oder ein unbekanntes oder widerrufenes.
403	forbidden	Dem Token fehlt der Scope dns, oder ein Schreibzugriff nennt die Zonenspitze, den Namen eines anderen Teams oder einen ungültigen Namen, oder einen anderen Typ als A, AAAA, CNAME und TXT.
403	resource_limit_exceeded	Der Schreibzugriff würde das Team über 200 Einträge bringen.
404	not_found	Eine unbekannte Zone, beim Lesen ein Name außerhalb deines Teams, oder eine nicht unterstützte Record-Set-Aktion.
405	method_not_allowed	Die Methode wird auf diesem Pfad nicht unterstützt.
429	rate_limit_exceeded	In Arbeit Über einer Anfragegrenze. Hetzners Clients wiederholen mit Wartezeit.
502	upstream_unavailable	Hetzners API war nicht erreichbar.

Lehnt Hetzner selbst einen Schreibzugriff ab, wird seine Antwort unverändert weitergegeben, mit eigenem Statuscode und code.

Beispiele

Mit curl deine Record-Sets auflisten und einen A-Eintrag anlegen:

export PAASBOX_DNS_TOKEN=pbdns_…

curl -s https://dns.paasbox.com/v1/zones/paasbox.app/rrsets \
  -H "Authorization: Bearer $PAASBOX_DNS_TOKEN"

curl -s -X POST https://dns.paasbox.com/v1/zones/paasbox.app/rrsets \
  -H "Authorization: Bearer $PAASBOX_DNS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "api.prod.acme", "type": "A", "ttl": 300, "records": [{"value": "203.0.113.7"}]}'

Mit dem hcloud-CLI die Einträge eines Wildcard-Namens ersetzen:

export HCLOUD_ENDPOINT=https://dns.paasbox.com/v1
export HCLOUD_TOKEN=pbdns_…

hcloud zone rrset set-records --record 203.0.113.8 paasbox.app '*.apps.acme' A

Demo-Namen

In Arbeit Auf einem Branch, nicht veröffentlicht: kurzlebige Namen unter demo.paasbox.app, jeder mit einem Token, das nur darunter schreiben darf.

Methode und Pfad	Authentifizierung	Was er tut
POST /demos	ein Team-Token, oder kein Token und {"course_code": "…"}	Legt einen Demo-Namen und sein Token an. Body: name (optional), ttl in Sekunden (optional; standardmäßig 4 Stunden, mindestens 300, höchstens 7 Tage). Das Token steht nur in dieser Antwort.
GET /demos	ein Team-Token	Die laufenden Demos des Teams, ohne Tokens.
GET /demos/{label}	das Token des Teams oder das der Demo	Eine Demo.
POST /demos/{label}/actions/extend	dasselbe	{"ttl": Sekunden}: Der Ablauf wird jetzt plus ttl, nie später als 7 Tage nach der Erstellung.
DELETE /demos/{label}	dasselbe	Löscht die Einträge der Demo sofort und widerruft ihr Token.

Ein Team hat höchstens 10 laufende Demos, eine Demo höchstens 20 Einträge. Ein Demo-Token funktioniert mit den Zonen-Endpunkten oben, beschränkt auf seinen eigenen Namen; es kann keine Demos anlegen oder auflisten.

DNS-Namen für deine ClusterWas der Dienst deinem Team gibt, was er ablehnt und wann er öffnet.

Deine erste App deployenLernschritt 2: eine App mit ihrer Datenbank, unter einem eigenen Namen, über HTTPS.