>_ NicAPI Dokumentation

Einführung

Die NicAPI ist die REST-Schnittstelle von LUMASERV. Über sie verwalten Sie Domains, DNS-Zonen, SSL-Zertifikate, Cloud-Server, IP-Adressen, Verträge und Rechnungen programmatisch. Diese Dokumentation wird automatisch aus der API erzeugt und listet jeden für Kunden verfügbaren Endpunkt mit seinen Parametern.

Derzeit dokumentiert: 266 Endpunkte in 15 Bereichen. Wählen Sie links einen Bereich oder nutzen Sie den Filter.

Basis-URL und Versionen

Alle Endpunkte liegen unter folgenden Basis-URLs. Die Versionsnummer ist Teil des Pfads und wird in dieser Dokumentation bei jedem Endpunkt angezeigt.

API v1:  https://connect.nicapi.eu/api/v1/
API v2:  https://connect.nicapi.eu/api/v2/

Authentifizierung

Jeder Aufruf (mit Ausnahme der als öffentlich gekennzeichneten Endpunkte) benötigt einen API-Token. Den Token erstellen Sie im Kundenbereich unter Account → API-Tokens. Übergeben Sie ihn entweder als HTTP-Header oder als Parameter authToken.

# Variante 1: HTTP-Header (empfohlen)
curl -H "Authorization: Bearer IHR_API_TOKEN" \
  "https://connect.nicapi.eu/api/v1/account/account"

# Variante 2: Parameter authToken
curl "https://connect.nicapi.eu/api/v1/account/account?authToken=IHR_API_TOKEN"

Anfragen

GET-Anfragen übergeben Parameter als Query-String, alle anderen Methoden im Request-Body – wahlweise als JSON (Content-Type: application/json) oder als Formular-Felder. Pfad-Parameter (z. B. {cloud_server}) werden direkt in die URL eingesetzt. Viele Endpunkte der API v1 identifizieren das Zielobjekt stattdessen über einen gewöhnlichen Parameter (z. B. domainName); dieser ist in der jeweiligen Parameter-Tabelle als Identifikator gekennzeichnet.

GET liest Daten, POST legt Ressourcen an oder löst Aktionen aus, PUT ändert Ressourcen und DELETE löscht sie.

Antworten

Antworten sind immer JSON und folgen demselben Aufbau: status ist "success" oder "error", data enthält die Nutzdaten, messages enthält Hinweise, Warnungen und Fehlermeldungen. Fehler werden zusätzlich über den HTTP-Statuscode (z. B. 400, 403, 404, 422) signalisiert.

{
  "status": "success",
  "data": { ... },
  "pagination": null,
  "messages": {
    "success": [],
    "warnings": [],
    "errors": []
  },
  "metadata": {
    "clientTransactionId": null,
    "serverTransactionId": "…"
  }
}

Listen: Paginierung, Sortierung und Filter

Endpunkte, die Listen zurückgeben, unterstützen folgende optionale Query-Parameter. Die Antwort enthält zusätzlich die Gesamtzahl: bei v2-Endpunkten im pagination-Objekt (mit Links auf die nächste und vorherige Seite), bei v1-Endpunkten in data.recordsTotal (ohne Filter), data.recordsFiltered (mit Filter) und data.recordsResult (Einträge dieser Seite).

curl -H "Authorization: Bearer IHR_API_TOKEN" \
  "https://connect.nicapi.eu/api/v1/domain/domains?limit=50&offset=100&order%5Bname%5D=asc"

Eckige Klammern in Query-Parametern müssen URL-kodiert werden (%5B / %5D), sonst interpretiert cURL sie als Platzhalter.

Filter

Listen lassen sich serverseitig filtern, entweder einfach per easyFilter (exakter Vergleich) oder flexibel per filter (Operatoren, UND/ODER, verschachtelte Gruppen). Beide Varianten können kombiniert werden; ihre Bedingungen gelten dann gemeinsam (UND). Gefiltert wird immer nur innerhalb der Objekte, auf die Ihr Token Zugriff hat.

Welche Felder filterbar und sortierbar sind, legt der jeweilige Endpunkt fest und steht in seiner Beschreibung. Nicht jedes Feld der Antwort ist filterbar.

Einfacher Filter: easyFilter

Jeder Eintrag easyFilter[feld]=wert prüft das Feld auf genau diesen Wert. Mehrere Einträge werden mit UND verknüpft.

curl -G -g -H "Authorization: Bearer IHR_API_TOKEN" \
  "https://connect.nicapi.eu/api/v1/domain/domains" \
  --data-urlencode "easyFilter[status]=ok"

Strukturierter Filter: filter

Ein Filter ist eine Gruppe aus einem connector (AND oder OR, Standard: AND) und einer Liste fields. Jeder Eintrag in fields ist entweder eine Bedingung aus key, operator und value oder selbst wieder eine Gruppe mit eigenem connector und eigenen fields. So lassen sich beliebige UND/ODER-Kombinationen abbilden.

# Domains, deren Name "shop" enthält und die vor 2027 ablaufen
curl -G -g -H "Authorization: Bearer IHR_API_TOKEN" \
  "https://connect.nicapi.eu/api/v1/domain/domains" \
  --data-urlencode "filter[connector]=AND" \
  --data-urlencode "filter[fields][0][key]=name" \
  --data-urlencode "filter[fields][0][operator]=LIKE" \
  --data-urlencode "filter[fields][0][value]=%shop%" \
  --data-urlencode "filter[fields][1][key]=expire" \
  --data-urlencode "filter[fields][1][operator]=<" \
  --data-urlencode "filter[fields][1][value]=2027-01-01" \
  --data-urlencode "order[expire]=asc"

-G hängt die Daten als Query-String an die URL an, --data-urlencode kodiert die Werte (z. B. % → %25) und -g verhindert, dass cURL eckige Klammern als Platzhalter deutet. Bei eigenen Clients müssen Werte ebenfalls URL-kodiert werden.

$result = NicAPI::get("domain/domains", [
    "filter" => [
        "connector" => "AND",
        "fields" => [
            ["key" => "name", "operator" => "LIKE", "value" => "%shop%"],
            ["key" => "expire", "operator" => "<", "value" => "2027-01-01"],
        ],
    ],
    "order" => ["expire" => "asc"],
]);

Operatoren

Gruppen verschachteln

Ein Eintrag ohne key gilt als Untergruppe. Das folgende Beispiel liefert Domains, die mit „shop“ beginnen und entweder gesperrt sind oder vor 2027 ablaufen – als Bedingung: name LIKE "shop%" AND (suspended_at IS NOT NULL OR expire < "2027-01-01").

$result = NicAPI::get("domain/domains", [
    "filter" => [
        "connector" => "AND",
        "fields" => [
            ["key" => "name", "operator" => "LIKE", "value" => "shop%"],
            [
                "connector" => "OR",
                "fields" => [
                    ["key" => "suspended_at", "operator" => "IS NOT NULL"],
                    ["key" => "expire", "operator" => "<", "value" => "2027-01-01"],
                ],
            ],
        ],
    ],
]);

Als Query-String entspricht die Untergruppe den Parametern filter[fields][1][connector]=OR, filter[fields][1][fields][0][key]=suspended_at usw.

Besondere Filterfelder

Wichtig zu wissen

• Unbekannte oder nicht filterbare Felder, Bedingungen ohne operator und unvollständige Einträge werden ignoriert; eine Bedingung mit unbekanntem Operator trifft auf nichts zu. Die Antwort nennt solche Angaben in messages.warnings, zusammen mit den zulässigen Feldern bzw. Operatoren. Ein anderer connector als AND oder OR und ein value, der kein einzelner Wert ist, werden mit einem Validierungsfehler abgelehnt; data.fields nennt den betroffenen Parameter.
• Vergleiche ohne value (außer IS NULL / IS NOT NULL) werden übersprungen, z. B. ein leeres Suchfeld.
• !=, <> und NOT LIKE treffen keine Objekte, bei denen das Feld leer (NULL) ist. Diese erfassen Sie bei Bedarf zusätzlich mit IS NULL in einer OR-Gruppe.
• Für mehrere Werte verwenden Sie IN mit kommagetrennter Liste oder eine OR-Gruppe.
• Auch bei order führen ein nicht sortierbares Feld oder eine andere Richtung als asc bzw. desc zu einem Validierungsfehler. Mehrere Sortierungen werden in der angegebenen Reihenfolge angewendet.
• Die Gesamtzahl in der Antwort (data.recordsFiltered bzw. pagination.total_element_count) bezieht sich auf das gefilterte Ergebnis, sodass sich limit und offset direkt zum Blättern durch die Treffer verwenden lassen.

PHP-Client

Für PHP steht ein Client zur Verfügung, der Authentifizierung und Request-Aufbau übernimmt. Die Beispiele bei jedem Endpunkt zeigen den Aufruf sowohl per cURL als auch mit dem PHP-Client.

composer require nicapi/php-client

use NicAPI\NicAPI;

NicAPI::init("IHR_API_TOKEN");

// API v1: Pfad relativ zur Basis-URL
$result = NicAPI::get("domain/domains", ["limit" => 50]);

if (NicAPI::wasSuccess()) {
    $domains = $result->data;
}

// API v2: vollständige URL übergeben
$result = NicAPI::get("https://connect.nicapi.eu/api/v2/cloud/servers");

if (NicAPI::wasSuccess()) {
    $servers = $result->data;
}