FastDDNS Client API

Überblick

Die FastDDNS-Client-API ermöglicht es jedem HTTP-fähigen Gerät – Routern, IP-Kameras, Skripten oder spezieller Updater-Software –, Ihren DNS-Hostnamen auf Ihre aktuelle IP-Adresse zu zeigen. Die API verwendet einfache GET-Anfragen: Ihr Client sendet Zugangsdaten und einen Hostnamen, und der Server antwortet mit einem kurzen Statuscode, der das Ergebnis angibt.

Der Server erkennt automatisch die öffentliche IP-Adresse des Clients über die eingehende Verbindung. Für die Angabe Ihrer IP sind keine zusätzlichen Parameter erforderlich.

Authentifizierung

Die API unterstützt zwei Authentifizierungsmethoden. Beide werden gleichwertig akzeptiert – wählen Sie die Methode, die sich auf Ihrem Gerät oder Router am einfachsten konfigurieren lässt.

Methode 1 — HTTP Basic Auth (in der URL eingebettet)

Die Zugangsdaten werden im Standardformat in die URL eingebettet user:password@host eingebettet. Dies wird von Routern, Kameras und HTTP-Client-Bibliotheken weitgehend unterstützt. Verwenden Sie den Updater Client Key aus Ihrem Dashboard als Passwort.

Methode 2 — Query-String-Parameter

Zugangsdaten werden als einfache Query-String-Parameter zusammen mithostname übergeben. Dies ist nützlich für Geräte und firmware, die keine HTTP-Basic-Auth-Header konfigurieren können, aber eine vollständig benutzerdefinierte URL-Zeichenfolge erlauben.

Beispiel für die Authentifizierung per Query-String:

Aktualisierung durchführen

Senden Sie eine einzelne GET-Anfrage, um die IP-Adresse eines bei Ihrem Konto registrierten hostname zu aktualisieren. Jede Anfrage aktualisiert jeweils einen hostname.

Endpunkt

URL-Format — Methode 1: HTTP Basic Auth

URL-Format — Methode 2: Query-String

Query-Parameter

Beispielanfragen

Methode 1 — HTTP Basic Auth über HTTPS:

Methode 2 — Query-String über HTTPS:

Verwendung von einfachem HTTP (nur zum Testen / in vertrauenswürdigen Netzwerken):

Rückgabecodes

Alle Update-Antworten geben den HTTP-Status 200 OK mit einem Klartext-Textkörper zurück. Ihr Client muss diesen Textkörper analysieren, um das tatsächliche Ergebnis des Updates zu bestimmen.

Zusammenfassung der Antwort

Client-IP abrufen

FastDDNS stellt einen einfachen Utility-Endpunkt bereit, der die öffentliche IP-Adresse zurückgibt, wie sie vom Server gesehen wird. Dies ist nützlich zum Debuggen, zur Überprüfung der IP, von der Ihr Gerät sendet, oder für die Verwendung in benutzerdefinierten Skripten, bevor der Update-Endpunkt aufgerufen wird.

Endpunkt

Antwort

Gibt HTTP zurück 200 OK wobei die erkannte öffentliche IP-Adresse als Klartext im Antworttext steht.

# Example response body
203.0.113.45RESPONSE

Beispielanfragen

Mit curl:

curl https://client.fastddns.net/dyndns/getipSHELL

Codebeispiele

Shell / cURL

# Recommended: let curl build the Authorization header (-u), so the
# credentials never appear in the URL.
HOSTNAME="myhome.fastddns.org"
USER_NAME="YOUR_UPDATE_USERNAME"
USER_PASS="YOUR_UPDATE_PASSWORD"
curl -s -u "${USER_NAME}:${USER_PASS}" "https://client.fastddns.net/?hostname=${HOSTNAME}"
# Legacy form, for devices that can only be given one URL field:
curl -s "https://client.fastddns.net/?hostname=${HOSTNAME}&user_name=${USER_NAME}&user_pass=${USER_PASS}"
# Check what IP the server sees from your device
curl -s "https://client.fastddns.net/dyndns/getip"SHELL

Python

import requests
HOSTNAME  = "testhost.fastddns.org"
USER_NAME = "YOUR_UPDATE_USERNAME"
USER_PASS = "YOUR_UPDATE_PASSWORD"
# Method 1: HTTP Basic Auth
resp = requests.get(
    "https://client.fastddns.net/",
    auth=(USER_NAME, USER_PASS),
    params={"hostname": HOSTNAME}
)
# Method 2: Query string
# resp = requests.get("https://client.fastddns.net/", params={
#     "hostname": HOSTNAME, "user_name": USER_NAME, "user_pass": USER_PASS
# })
body = resp.text.strip()
if body.startswith("good"):
    print(f"Updated successfully: {body}")
elif body.startswith("nochg"):
    print(f"No change needed: {body}")
elif body == "badauth":
    print("Authentication failed. Check credentials.")
elif body == "nohost":
    print("Hostname not found.")
elif body == "911":
    print("Server error. Try again later.")PYTHON

PHP

<?php
$hostname  = 'testhost.fastddns.org';
$user_name = 'YOUR_UPDATE_USERNAME';
$user_pass = 'YOUR_UPDATE_PASSWORD';
// Recommended: Basic Auth in a request header, so the password is not
// part of the URL and cannot leak through logs or error messages.
$url = "https://client.fastddns.net/?hostname=" . urlencode($hostname);
$auth = 'Basic ' . base64_encode($user_name . ':' . $user_pass);
// Method 2: Query string credentials
// $url = "https://client.fastddns.net/?hostname=" . urlencode($hostname)
//      . "&user_name=" . urlencode($user_name)
//      . "&user_pass=" . urlencode($user_pass);
$ctx = stream_context_create(['http' => [
    'timeout' => 10,
    'header'  => "Authorization: {$auth}\r\n",
]]);
$body = trim(file_get_contents($url, false, $ctx));
switch (true) {
    case str_starts_with($body, 'good'):
        echo "Updated: {$body}\n"; break;
    case str_starts_with($body, 'nochg'):
        echo "No change: {$body}\n"; break;
    case $body === 'badauth':
        echo "Auth failed. Check hostname credentials.\n"; break;
    case $body === 'nohost':
        echo "Hostname not found.\n"; break;
    case $body === '911':
        echo "Server error, retry later.\n"; break;
}PHP

Bash (Cron / Router-Skript)

#!/bin/bash
HOSTNAME="testhost.fastddns.org"
USER_NAME="YOUR_UPDATE_USERNAME"
USER_PASS="YOUR_UPDATE_PASSWORD"
# Method 1: HTTP Basic Auth
RESULT=$(curl -s -u "${USER_NAME}:${USER_PASS}" "https://client.fastddns.net/?hostname=${HOSTNAME}")
# Method 2: Query string (uncomment to use instead)
# RESULT=$(curl -s "https://client.fastddns.net/?hostname=${HOSTNAME}&user_name=${USER_NAME}&user_pass=${USER_PASS}")
case "$RESULT" in
  good*)   echo "[OK] $RESULT" ;;
  nochg*)  echo "[OK] $RESULT" ;;
  badauth) echo "[ERR] Bad credentials — check hostname user/pass"; exit 1 ;;
  nohost)  echo "[ERR] Hostname not found"; exit 1 ;;
  911)     echo "[ERR] Server error, retry later"; exit 1 ;;
  *)       echo "[WARN] Unknown response: $RESULT" ;;
esacBASH

Fehlerbehebung

Ich erhalte badauth

Die angegebenen user_name oder user_pass stimmen nicht mit den diesem hostname zugewiesenen Zugangsdaten überein. Jeder hostname hat eigene, unabhängige Zugangsdaten – Sie finden sie in Ihrem Dashboard unter Hostnames → Details. Beachten Sie, dass diese Zugangsdaten spezifisch für den hostname sind und nicht für die Anmeldung am FastDDNS-Verwaltungsportal verwendet werden können. Wenn Sie die Zugangsdaten kürzlich zurückgesetzt haben, aktualisieren Sie alle Geräte, die diesen hostname verwenden.

Ich erhalte nohost

Der hostname im hostname-Parameter existiert nicht oder gehört nicht zu dem Konto, das durch die angegebenen Zugangsdaten identifiziert wird. Überprüfen Sie den hostname auf Tippfehler, bestätigen Sie, dass er in Ihrem Dashboard aufgeführt ist, und prüfen Sie, ob user_name und user_pass mit diesem spezifischen hostname .

Der Server erkennt die falsche IP

Der Server verwendet die Quell-IP der TCP-Verbindung. Wenn sich Ihr Gerät hinter einem NAT-router befindet, wird die öffentliche IP des routers erkannt – was in der Regel das gewünschte Verhalten ist. Wenn Sie ein VPN oder einen Proxy verwenden, sieht der Server stattdessen die VPN-/Proxy-Ausgangs-IP. Verwenden Sie den _NT2_das {}Endpunkt „Get Client IP“

Ich erhalte 911

Dies deutet auf ein vorübergehendes serverseitiges Problem hin. Warten Sie mindestens 5 Minuten, bevor Sie es erneut versuchen. Senden Sie Anfragen nicht in einer schnellen Schleife – dies kann eine Ratenbegrenzung auslösen. Überprüfen Sie die FastDDNS-Statusseite auf aktive Vorfälle.

Wie oft sollte ich den Update-Endpunkt abfragen?

Wir empfehlen, alle 5 Minuten auf IP-Änderungen zu prüfen. Wenn sich Ihre IP nicht geändert hat, gibt der Server nochg zurück, was ein leichter No-op ist. Häufigeres Abfragen als einmal pro Minute wird nicht empfohlen und kann zu einer Ratenbegrenzung führen.