API клиента FastDDNS

Обзор

API клиента FastDDNS позволяет любому устройству с поддержкой HTTP — роутеру, IP-камере, скрипту или специальному программному обеспечению для обновления — поддерживать привязку вашего hostname к текущему IP-адресу. API использует простую схему GET-запросов: клиент отправляет учётные данные и hostname, а сервер отвечает коротким кодом состояния, указывающим результат.

Сервер автоматически определяет публичный IP-адрес клиента по входящему соединению. Дополнительные параметры для указания IP не требуются.

Аутентификация

API поддерживает два метода аутентификации. Оба принимаются в равной степени — выберите тот, который проще настроить на вашем устройстве или роутере.

Метод 1 — HTTP Basic Auth (встроенные в URL)

Учётные данные встраиваются в URL в стандартном формате user:password@hostформат. Это широко поддерживается маршрутизаторами, камерами и библиотеками HTTP-клиентов. Используйте Updater Client Key из вашей панели в качестве пароля.

Метод 2 — параметры строки запроса

Учетные данные передаются в виде обычных параметров запроса вместе с hostname. Это полезно для устройств и firmware, которые не могут настроить заголовки HTTP Basic Auth, но позволяют указать полностью настраиваемую строку URL.

Пример аутентификации с использованием строки запроса:

Выполнить обновление

Отправьте один GET-запрос, чтобы обновить IP-адрес hostname, зарегистрированного в вашей учётной записи. Каждый запрос обновляет по одному имени хоста за раз.

Конечная точка

Формат URL — метод 1: HTTP Basic Auth

Формат URL — метод 2: строка запроса

Параметры запроса

Примеры запросов

Метод 1 — HTTP Basic Auth через HTTPS:

Метод 2 — строка запроса через HTTPS:

Использование обычного HTTP (только для тестирования и доверенных сетей):

Коды возврата

Все ответы на обновление возвращают статус HTTP 200 ОК с простым текстовым содержимым. Ваш клиент должен проанализировать это содержимое, чтобы определить фактический результат обновления.

Сводка ответа

Получить IP клиента

FastDDNS предоставляет простую конечную точку, которая возвращает публичный IP-адрес, видимый сервером. Это полезно для отладки, проверки IP-адреса, с которого отправляет запрос ваше устройство, а также для использования в пользовательских скриптах перед вызовом конечной точки обновления.

Конечная точка

Ответ

Возвращает HTTP 200 ОК с обнаруженным публичным IP-адресом в виде обычного текста в теле ответа.

# Example response body
203.0.113.45RESPONSE

Примеры запросов

С использованием curl:

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

Примеры кода

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)

#!/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

Устранение неполадок

Я получаю badauth

Предоставленные user_name или user_pass не совпадают с учётными данными, назначенными этому hostname. У каждого hostname есть отдельные учётные данные — найдите их в панели управления в разделе Имена хозяев → подробности. Обратите внимание: эти учётные данные предназначены только для этого hostname и не могут использоваться для входа в портал управления FastDDNS. Если вы недавно сбросили учётные данные, обновите их на всех устройствах, использующих этот hostname.

Я получаю nohost

Имя хоста в параметре hostname отсутствует или не принадлежит аккаунту, указанному в предоставленных учётных данных. Проверьте hostname на наличие опечаток, убедитесь, что он указан в панели управления, и проверьте, что user_name и user_pass соответствуют Это конкретное имя хозяина.

Сервер обнаруживает неправильный IP

Сервер использует исходный IP-адрес TCP-соединения. Если устройство находится за NAT-router, сервер обнаружит публичный IP-адрес router — обычно это и требуется. Если вы используете VPN или прокси, сервер увидит внешний IP-адрес VPN или прокси. Используйте getip endpoint, чтобы проверить, какой IP-адрес сервер видит с вашего устройства.

Я получаю 911

Это указывает на временную проблему на стороне сервера. Подождите не менее 5 минут перед повторной попыткой. Не отправляйте запросы в быстром цикле — это может привести к ограничению частоты запросов. Проверьте страницу статуса FastDDNS на наличие активных инцидентов.

Как часто следует опрашивать endpoint обновления?

Рекомендуем проверять изменения IP каждые 5 минут. Если IP-адрес не изменился, сервер возвращает nochg, что представляет собой лёгкую операцию без изменений. Не рекомендуется выполнять опрос чаще одного раза в минуту: это может привести к ограничению частоты запросов.