API кіравання DNS

Агляд

DNS API забяспечвае поўнае кіраванне DNS- зонамі і запісамі. Усе зоны знаходзяцца на аўтарытэтных серверах імёнаў VPS.org з аўтаматычным стварэннем і разгортваннем файлаў зон BIND9.

Інфраструктура сервера імёнаў

• ns1.vps.org (38.248.6.195) - Галоўны гаспадар з убудаваным подпісам DNSSEC
• ns2.vps.org (38.248.6.196) - Другі падкантрольныя
• ns3.vps.org (38.248.6.197) - Другі падкантрольныя

Ключавыя магчымасці

• Аўтаматычнае стварэньне і разьмяшчэньне файлаў зон BIND9
• Перадача зон праз аўтэнтыфікацыю TSIG (рэплікацыя master- slave)
• Падтрымка ўсіх асноўных тыпаў запісаў DNS (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA)
• Фільтрацыя імёнаў даменаў і ідэнтыфікацыя зон на аснове UUID
• Убудаваныя маршруты для кіравання запісамі па зоне

Аўтэнтыфікацыя

Усе запыты DNS API патрабуюць аўтэнтыфікацыі з дапамогай токенаў носьбіта. Стварыце токены API з панэлі кіравання вашага рахунку на /account/developers/ з наступнымі правамі:

• dns:list - Прагляд зон і запісаў DNS
• dns:create - Стварыць новыя зоны і запісы
• dns:update - Змяніць існуючыя зоны і запісы
• dns:delete - Выдаліць зоны і запісы
• dns:* - Поўны доступ да кіравання DNS

Прыклад

Authorization: Bearer vps_abc123def456...

Спіс усіх DNS-зон

Атрымаць спіс усіх зон DNS, якія належаць аўтарызаванаму карыстальніку. Падтрымліваецца фільтраванне па імя дамена.

Параметры запыту

Прыклад запыту

curl -X GET "https://admin.vps.org/api/v1/dns-zones/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

import requests

url = "https://admin.vps.org/api/v1/dns-zones/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers)
print(response.json())

const response = await fetch('https://admin.vps.org/api/v1/dns-zones/', {
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

const zones = await response.json();
console.log(zones);

Прыклад адказу

[
  {
    "uuid": "abc123-def456-ghi789",
    "domain": "example.com",
    "created_at": "2024-01-15T10:30:00Z",
    "record_count": 12
  },
  {
    "uuid": "xyz789-uvw456-rst123",
    "domain": "myapp.io",
    "created_at": "2024-06-20T14:15:00Z",
    "record_count": 8
  }
]

Палі адказаў

Коды стану адказу

Атрымаць падрабязнасці зоны DNS

Атрымаць падрабязную інфармацыю пра адмысловую зону DNS, уключаючы ўсе запісы.

Параметры шляху

Прыклад адказу

{
  "uuid": "abc123-def456-ghi789",
  "domain": "example.com",
  "created_at": "2024-01-15T10:30:00Z",
  "record_count": 5,
  "records": [
    {
      "uuid": "rec-001",
      "record_type": "A",
      "name": "@",
      "value": "192.0.2.1",
      "ttl": 3600,
      "priority": null,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "uuid": "rec-002",
      "record_type": "MX",
      "name": "@",
      "value": "mail.example.com",
      "ttl": 3600,
      "priority": 10,
      "created_at": "2024-01-15T10:32:00Z"
    }
  ]
}

Коды стану адказу

Стварыць зону DNS

Стварыць новую зону DNS для дамену. Зона будзе адразу ж разгорнута на VPS.org сервераў імёнаў.

Запытаць параметры цела

Прыклад запыту

curl -X POST "https://admin.vps.org/api/v1/dns-zones/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "newdomain.com"}'

import requests

url = "https://admin.vps.org/api/v1/dns-zones/"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
data = {"domain": "newdomain.com"}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const response = await fetch('https://admin.vps.org/api/v1/dns-zones/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({domain: 'newdomain.com'})
});

const zone = await response.json();
console.log(zone);

Прыклад адказу

{
  "uuid": "new-zone-uuid",
  "domain": "newdomain.com",
  "created_at": "2026-01-18T16:45:00Z",
  "record_count": 0,
  "records": []
}

Коды стану адказу

Выдаліць зону DNS

Выдаліць зону DNS і ўсе звязаныя з ёй запісы. Гэтае дзеянне нельга адмяніць.

Параметры шляху

Коды стану адказу

Спіс запісаў DNS у зоне

Атрымаць усе запісы DNS для вызначанай зоны (ўбудаваны маршрут).

Параметры шляху

Прыклад запыту

curl -X GET "https://admin.vps.org/api/v1/dns-zones/{uuid}/records/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Прыклад адказу

[
  {
    "uuid": "rec-001",
    "record_type": "A",
    "name": "@",
    "value": "192.0.2.1",
    "ttl": 3600,
    "priority": null,
    "created_at": "2024-01-15T10:30:00Z"
  },
  {
    "uuid": "rec-002",
    "record_type": "MX",
    "name": "@",
    "value": "mail.example.com",
    "ttl": 3600,
    "priority": 10,
    "created_at": "2024-01-15T10:32:00Z"
  }
]

Стварыць запіс DNS у зоне

Дадаць новы запіс DNS у вызначаную зону (ўбудаваны маршрут).

Запытаць параметры цела

Прыклад запыту

curl -X POST "https://admin.vps.org/api/v1/dns-zones/{uuid}/records/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "record_type": "A",
    "name": "www",
    "value": "192.0.2.1",
    "ttl": 3600
  }'

import requests

url = f"https://admin.vps.org/api/v1/dns-zones/{zone_uuid}/records/"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "record_type": "A",
    "name": "www",
    "value": "192.0.2.1",
    "ttl": 3600
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Коды стану адказу

Кіраванне запісамі DNS (прамы доступ)

Усе звароты да карыстальнікаў у DNS-серверы адпраўляюцца ў UUID.

Наяўныя аперацыі

• GET /api/v1/dns-records/{uuid}/ - Retrieve record details
• PUT /api/v1/dns-records/{uuid}/ - Full update (all fields required)
• PATCH /api/v1/dns-records/{uuid}/ - Partial update (only changed fields)
• DELETE /api/v1/dns-records/{uuid}/ - Delete record

Параметры запыту (для GET / api/ v1/ dns- records /)

Прыклад: абнаўленне TTL запісу

curl -X PATCH "https://admin.vps.org/api/v1/dns-records/{rec-uuid}/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttl": 1800}'

Supported DNS Record Types

Лепшыя практыкі

Настаўленні TTL

• Выпуск (стабільны): 3600- 86400 секунд (1- 24 гадзіны)
• Перад міграцыяй: 300- 600 секунд (5- 10 хвілін) - зніжэнне TTL перад запланаванымі зменамі
• Разпрацоўка: 300- 1800 секунд (5- 30 хвілін) для хутчэйшага тэсту

Звычайныя шаблоны

• Каранёвы дамен (@): Выкарыстоўваць запісы A/ AAAA, а не CNAME
• www паддамен: Можна выкарыстоўваць CNAME, які паказвае на каранёвы або асобны запіс A
• Эл. пошта (MX): Заўсёды ўключаць прыярытэт, ніжэйшы лік = вышэйшы прыярытэт
• CNAME: Нельга суіснаваць з іншымі тыпамі запісаў з такой жа назвай

Бяспека

• Запісы CAA: Вызначыць, якія CA могуць выдаваць сертыфікаты
• Стварыць новы спіс распаўсюджвання Настаўленні спраўджвання асобы пры адпраўцы электроннай поштыName
• Рэгулярныя праверкі: Прагляд запісаў DNS штоквартальна, выдаленне невыкарыстоўваных запісаў

Апрацоўка памылак

Частыя памылкі

Прыклад адказу на памылку

{
  "detail": "MX records require a priority value",
  "error_code": "validation_error",
  "field": "priority"
}

Правяраць змены DNS

Праверыць распаўсюджванне запісу

# Query A record
dig example.com A

# Query specific nameserver
dig @ns1.vps.org example.com

# Query MX records
dig example.com MX

# Check all records
dig example.com ANY

Інструменты ў сеціве

• whatsmydns.net: Check global DNS propagation
• dnschecker.org: Multi-location DNS lookup
• mxtoolbox.com: Email-related DNS testing