API quản lý DNS

Tổng quan

API DNS cung cấp quản lý đầy đủ các vùng và ghi chú DNS. Tất cả các vùng được lưu trữ trên máy chủ tên có thẩm quyền của VPS.org với việc tạo và triển khai tập tin vùng BIND9 tự động.

Hệ thống máy phục vụ tên

• ns1.vps.org (38.248.6.195) - Thủ trưởng chính với ký tên DNSSEC trong dòng
• ns2.vps.org (38.248.6.196) - Thứ hai
• ns3.vps.org (38.248.6.197) - Thứ hai

Tính năng chính

• Tạo và triển khai tập tin vùng BIND9 tự động
• Chuyển vùng qua xác thực TSIG (được sao chép chủ-như)
• Hỗ trợ tất cả các kiểu ghi DNS chính (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA)
• Tự lọc tên miền và xác định vùng dựa trên UUID
• Đường lồng cho quản lý ghi chép cụ thể vùng

Xác thực

Tất cả yêu cầu API DNS cần xác thực token Bearer. Tạo token API từ bảng điều khiển tài khoản của bạn tại /account/developers/ với quyền sau:

• dns:list - Xem các vùng và ghi chú DNS
• dns:create - Tạo vùng và ghi chú mới
• dns:update - Sửa đổi các vùng và ghi chép hiện có
• dns:delete - Xoá vùng và ghi chú
• dns:* - Truy cập quản lý DNS đầy đủ

Ví dụ

Authorization: Bearer vps_abc123def456...

Liệt kê tất cả các vùng DNS

Lấy danh sách các vùng DNS thuộc về người dùng đã xác thực. Hỗ trợ lọc theo tên miền.

Tham số truy vấn

Ví dụ về yêu cầu

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);

Ví dụ về câu trả lời

[
  {
    "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
  }
]

Các trường phản hồi

Mã trạng thái phản hồi

Lấy chi tiết khu vực DNS

Lấy thông tin chi tiết về một khu vực DNS cụ thể, bao gồm tất cả các ghi chép.

Tham số đường dẫn

Ví dụ về câu trả lời

{
  "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"
    }
  ]
}

Mã trạng thái phản hồi

Tạo khu vực DNS

Tạo một vùng DNS mới cho một miền. Khu vực này sẽ được triển khai ngay lập tức cho VPS.org máy phục vụ tên.

Các tham số thân yêu cầu

Ví dụ về yêu cầu

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);

Ví dụ về câu trả lời

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

Mã trạng thái phản hồi

Xoá vùng DNS

Xoá vĩnh viễn vùng DNS và tất cả các ghi chép liên quan. Hành động này không thể được hủy bỏ.

Tham số đường dẫn

Mã trạng thái phản hồi

Danh sách các ghi DNS trong khu vực

Lấy tất cả các ghi chú DNS cho một khu vực cụ thể (lối đi lồng).

Tham số đường dẫn

Ví dụ về yêu cầu

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

Ví dụ về câu trả lời

[
  {
    "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"
  }
]

Tạo ghi DNS trong vùng

Thêm một ghi chú DNS mới cho một khu vực cụ thể (đường lưới).

Các tham số thân yêu cầu

Ví dụ về yêu cầu

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())

Mã trạng thái phản hồi

Quản lý ghi chú DNS (tạo trực tiếp)

Hoạt động CRUD đầy đủ trên các ghi chú DNS cá nhân sử dụng UUID ghi.

Hoạt động có sẵn

• 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

Tham số truy vấn (cho GET /api/v1/dns-records/)

Ví dụ: Cập nhật TTL của một ghi chú

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

Thực hành tốt nhất

Cấu hình TTL

• Sản xuất (bền vững): 3600- 86400 giây (1- 24 giờ)
• Trước khi di chuyển: 300- 600 giây (5- 10 phút) - Giảm TTL trước khi thay đổi kế hoạch
• Phát triển: 300-1800 giây (5-30 phút) để kiểm tra nhanh hơn

Mẫu chung

• Miền gốc (@): Dùng ghi A/ AAAA, không phải CNAME
• miền con www: Có thể dùng CNAME chỉ vào gốc hoặc tách một ghi chép
• Thư điện tử (MX): Luôn bao gồm ưu tiên, số nhỏ hơn = ưu tiên cao hơn
• CNAME: Không thể tồn tại cùng với các kiểu ghi chép khác với cùng tên

An ninh

• CAA Records: Chỉ ra CA nào có thể cấp chứng nhận
• SPF/DKIM/DMARC: Cấu hình xác thực email để ngăn chặn giả mạoName
• Kiểm toán thường xuyên: Kiểm tra các ghi chú DNS hàng quý, gỡ bỏ các mục không dùng

Xử lý lỗi

Lỗi phổ biến

Trả lời lỗi ví dụ

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

Thử nghiệm thay đổi DNS

Kiểm tra sự lan truyền ghi chú

# 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

Dùng công cụ trực tuyến

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