Domain-API im Vergleich: RDAP, EPP, Registrar-REST

Wer „Domain-API“ sucht, meint meistens eines von drei Dingen: prüfen, ob ein Name frei ist, Daten zu einer bestehenden Domain abrufen oder Domains per Code registrieren und verwalten. Für jedes davon gibt es andere Schnittstellen, und die Unterschiede bei Zugang, Kosten und Limits sind groß. Wer das vorher sortiert, spart sich eine Integration, die am Ende das Falsche kann.

Domain-API ist nicht gleich Domain-API

Grob lassen sich vier Arten unterscheiden. Sie bauen aufeinander auf: Registries sprechen EPP mit Registraren, Registrare bieten Kunden REST-APIs an, und die öffentliche Auskunft läuft über RDAP oder Whois.

Wie RDAP und Whois in PHP aussehen, beschreiben die Beiträge zu RDAP mit PHP und Whois per Port 43. Hier geht es um die Frage, welche Schnittstelle für welches Projekt passt.

EPP: das Protokoll hinter jeder Registrierung

Jede Registrierung landet am Ende als EPP-Befehl bei der Registry. EPP (Extensible Provisioning Protocol) ist in RFC 5730 bis 5734 spezifiziert, arbeitet mit XML-Nachrichten über eine dauerhafte TLS-Verbindung und kennt Befehle wie <check>, <create>, <renew> und <transfer>. Ein <domain:check> beantwortet die Verfügbarkeit verbindlich, inklusive Reservierungen.

Der Haken: Zugang bekommen nur akkreditierte Registrare. Bei gTLDs heißt das ICANN-Akkreditierung plus Vertrag mit jeder einzelnen Registry, bei .de eine Mitgliedschaft bei der DENIC. Für eine Agentur, die 200 Kundendomains verwaltet, lohnt sich dieser Aufwand nicht. Sie nutzt die API eines Registrars, der den EPP-Teil übernimmt.

Registrar-APIs: worauf du achten solltest

Registrar-APIs unterscheiden sich stark. Vor einer Integration lohnt es sich, ein paar Punkte zu klären, bevor die erste Zeile Code entsteht:

• Authentifizierung: API-Key, OAuth oder persönlicher Token? Lässt sich ein Token einzeln widerrufen?
• Preisauskunft: Liefert die API Registrierungs- und Verlängerungspreis getrennt? Ein günstiger Einstiegspreis mit teurer Verlängerung fällt sonst erst nach einem Jahr auf.
• Sandbox: Gibt es eine Testumgebung, in der Bestellungen nichts kosten?
• Limits: Welche Rate-Limits gelten, und kommen sie als HTTP 429 mit Retry-After zurück?
• Abdeckung: Welche Endungen sind über die API verfügbar, und gelten für Länderendungen Sonderregeln wie Wohnsitz oder Treuhänder?
• Zahlung: Wird ein Guthabenkonto belastet, oder braucht jede Bestellung eine Zahlungsfreigabe?

Der letzte Punkt klingt nach Buchhaltung, ist aber eine Architekturfrage. Eine API, die ein Prepaid-Konto belastet, erlaubt vollautomatische Registrierungen. Eine API, die einen Checkout-Link liefert, braucht immer einen Menschen im Ablauf.

Die betadomain-API für PHP-Projekte

betadomain bietet zwei Ebenen an, beide in der Entwicklerdokumentation beschrieben. Die erste ist eine öffentliche REST-API mit zwei lesenden Endpunkten, ohne Key und ohne Konto: POST /api/domain/check für eine konkrete Domain und POST /api/domain/search für einen Namen über acht beliebte Endungen. Fair Use: 30 Anfragen pro Minute und 300 pro sechs Stunden je IP. Eine OpenAPI-3.1-Beschreibung liegt unter /openapi.json.

Die zweite Ebene ist ein MCP-Server unter /api/mcp, der neben den Lese-Tools mit einem persönlichen Zugriffstoken auch eigene Domains auflistet und Bestellungen vorbereitet. Mehr dazu im Beitrag zum MCP-Server für Domains.

Ein schlanker PHP-Client für die REST-Endpunkte:

<?php
declare(strict_types=1);

final class BetadomainClient
{
    public function __construct(private string $base = 'https://betadomain.de') {}

    public function check(string $domain): array
    {
        return $this->post('/api/domain/check', ['domain' => $domain]);
    }

    /** @return list<array{domain:string, tld:string, available:?bool, priceEur:?float}> */
    public function search(string $name): array
    {
        return $this->post('/api/domain/search', ['query' => $name])['results'];
    }

    private function post(string $path, array $payload): array
    {
        $ch = curl_init($this->base . $path);
        curl_setopt_array($ch, [
            CURLOPT_POST           => true,
            CURLOPT_POSTFIELDS     => json_encode($payload, JSON_THROW_ON_ERROR),
            CURLOPT_HTTPHEADER     => ['Content-Type: application/json', 'Accept: application/json'],
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT        => 15,
            CURLOPT_HEADER         => true,
        ]);
        $raw = curl_exec($ch);
        if ($raw === false) {
            throw new RuntimeException(curl_error($ch));
        }
        $status  = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        $headers = substr($raw, 0, curl_getinfo($ch, CURLINFO_HEADER_SIZE));
        $body    = substr($raw, curl_getinfo($ch, CURLINFO_HEADER_SIZE));

        if ($status === 429) {
            $wait = preg_match('/^Retry-After:\s*(\d+)/mi', $headers, $m) ? (int) $m[1] : 60;
            throw new RuntimeException("Rate-Limit, erneut in {$wait}s");
        }
        $data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
        if ($status >= 400) {
            throw new RuntimeException($data['error'] ?? "HTTP $status");
        }
        return $data;
    }
}

$api = new BetadomainClient();
foreach ($api->search('phpexperten-test') as $r) {
    $state = match ($r['available']) {
        true    => 'frei',
        false   => 'vergeben',
        default => 'unbekannt',
    };
    printf("%-26s %s\n", $r['domain'], $state);
}

Die Suche lieferte beim Test acht Ergebnisse von phpexperten-test.de bis phpexperten-test.dev, jeweils mit available und priceEur. Die Preise kommen aus derselben Liste wie auf der Website, für .de aktuell 2,99 €, für .io 61,99 €, und die Verlängerung kostet jeweils dasselbe.

Fehlerfälle, die dein Client kennen muss

Eine API, die im Erfolgsfall sauber antwortet, ist leicht anzubinden. Interessant wird es bei den Rändern. Für die beiden öffentlichen Endpunkte sind das vier Fälle:

• HTTP 400 bei ungültigem Namen. Die Suche akzeptiert im Namensteil nur a bis z, Ziffern und Bindestrich. Umlaute gehören in den Check-Endpunkt oder vorher in Punycode.
• HTTP 429 bei überschrittenem Limit, mit Retry-After in Sekunden. Der Client oben liest den Header und gibt die Wartezeit weiter.
• "supported": false im Ergebnis, wenn betadomain die Endung nicht führt. Dann gab es bewusst keine Abfrage bei der Registry.
• "available": null mit "error": true in einem einzelnen Suchergebnis, wenn die Abfrage für genau diese Endung fehlschlug. Die übrigen Ergebnisse bleiben gültig.

Der letzte Fall ist der tückischste, weil PHP null in einem if wie false behandelt. Wer $r['available'] ? 'frei' : 'vergeben' schreibt, meldet einen Timeout als „vergeben“. Das ist harmloser als umgekehrt, aber trotzdem falsch, deshalb das match mit drei Zweigen im Beispiel.

Welche Domain-API für welches Projekt?

Meine Faustregel nach einigen Integrationen:

Wer nur Eingaben validieren will, braucht übrigens gar keine API. Ob ein String formal ein Domainname ist, prüft ein Regex in Mikrosekunden; wie der aussieht, steht unter Domain validieren mit Regex.

Die vollständigen Preise aller Endungen, die über die API abfragbar sind, findest du in der Preisliste mit allen Endungen. Für einen ersten Versuch ohne Code reicht die Suche nach freien Domains.