واجهة برمجة تطبيقات إدارة نظام أسماء النطاقات (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 آليا
عمليات نقل المناطق عن طريق التحقق من هوية نظام إدارة المعلومات الجغرافية (استنساخ رئيسي - ثانوي)
دعم جميع أنواع السجلات الرئيسية لنظام أسماء النطاقات (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA)
ترشيح أسماء النطاقات وتحديد المناطق على أساس UUID
مسارات متداخلة لإدارة السجلات الخاصة بالمناطق

المصادقة

جميع طلبات DNS API تتطلب توثيق حامل الرموز. توليد رموز API من لوحة حسابك على /account/developers/ مع الإذن التالي:

dns:list - عرض مناطق وسجلات DNS
dns:create - إنشاء مناطق وسجلات جديدة
dns:update - تعديل المناطق والسجلات القائمة
dns:delete - حذف المناطق والسجلات
dns:* - الوصول الكامل إلى إدارة أسماء النطاقات

مثال

Authorization: Bearer vps_abc123def456...

مهم: تظهر رموز API مرة واحدة فقط أثناء الإنشاء. اخزنها بأمان. إذا فقدت رموزاً، يجب أن تنتج واحدة جديدة.

يحصل /api/v1/dns-zones/

عرض جميع نطاقات نظام أسماء النطاقات (DNS)

استعادة قائمة صفحة من جميع مناطق DNS التي يملكها المستخدم المصدق عليه. يدعم الترشيح حسب اسم المجال.

معلمات الاستعلام

البارامترات	يكتب	مطلوب	وصف المشروع
`domain`	string	لا	Filter zones by exact domain name (e.g., `example.com`)

مثال على الطلب

cURL

Python

JavaScript

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

حقول الاستجابة

الميدان	يكتب	وصف المشروع
`uuid`	string	Unique zone identifier (used in API requests)
`domain`	string	Domain name for this DNS zone
`created_at`	datetime	Zone creation timestamp (ISO 8601 format)
`record_count`	integer	Total number of DNS records in this zone

رموز حالة الاستجابة

200	Successfully retrieved DNS zones list
401	Unauthorized - Invalid or missing API token
403	Forbidden - Token lacks `dns:list` permission

يحصل /api/v1/dns-zones/{uuid}/

احصل على تفاصيل منطقة DNS

استرجاع معلومات مفصلة عن منطقة DNS محددة، بما في ذلك جميع السجلات.

معلمات المسار

البارامترات	يكتب	مطلوب	وصف المشروع
`uuid`	string	نعم	Unique zone identifier

مثال على الاستجابة

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

رموز حالة الاستجابة

200	Successfully retrieved zone details
404	Zone not found or not owned by user

الوظائف /api/v1/dns-zones/

إنشاء منطقة DNS

إنشاء منطقة DNS جديدة لنطاق. المنطقة سوف يتم نشرها فورا إلى VPS.org خادم الاسم.

معلمات نص الطلب

البارامترات	يكتب	مطلوب	وصف المشروع
`domain`	string	نعم	Domain name (e.g., `example.com`)

مثال على الطلب

cURL

Python

JavaScript

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

رموز حالة الاستجابة

201	DNS zone created successfully
400	Bad Request - Invalid domain name or zone already exists
403	Forbidden - Token lacks `dns:create` permission

يمسح /api/v1/dns-zones/{uuid}/

حذف منطقة DNS

حذف منطقة DNS وجميع السجلات المرتبطة بها بشكل دائم. لا يمكن إلغاء هذا الإجراء.

معلمات المسار

البارامترات	يكتب	مطلوب	وصف المشروع
`uuid`	string	نعم	Unique zone identifier

رموز حالة الاستجابة

204	Zone deleted successfully (no response body)
403	Forbidden - Token lacks `dns:delete` permission
404	Zone not found

يحصل /api/v1/dns-zones/{uuid}/records/

قائمة سجلات DNS في المنطقة

استرجاع جميع سجلات DNS لمنطقة محددة (مسار متداخل).

معلمات المسار

البارامترات	يكتب	مطلوب	وصف المشروع
`uuid`	string	نعم	Zone UUID

مثال على الطلب

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

الوظائف /api/v1/dns-zones/{uuid}/records/

إنشاء سجل DNS في المنطقة

إضافة سجل DNS جديد إلى منطقة محددة (مسار متداخل).

معلمات نص الطلب

البارامترات	يكتب	مطلوب	وصف المشروع
`record_type`	string	نعم	Record type: A, AAAA, CNAME, MX, TXT, NS, SRV, CAA
`name`	string	نعم	Record name (`@` for root, subdomain, or FQDN)
`value`	string	نعم	Record value (IP address, hostname, text)
`ttl`	integer	No	Time to live in seconds (default: 3600)
`priority`	integer	For MX/SRV	Priority (required for MX and SRV records)

مثال على الطلب

cURL

Python

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

رموز حالة الاستجابة

201	DNS record created successfully
400	Bad Request - Invalid parameters or validation error (e.g., MX record missing priority)

GET PUT PATCH DELETE /api/v1/dns-records/{uuid}/

إدارة سجلات DNS (الوصول المباشر)

عمليات CRUD كاملة على سجلات 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

بارامترات الاستفسار (لطلب /api/v1/dns-records/)

Parameter	يكتب	وصف المشروع
`zone`	string	Filter records by zone UUID
`record_type`	string	Filter by record type (A, AAAA, MX, etc.)

مثال: تحديث تاريخ التشغيل لسجل

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

يكتب	Purpose	Example Value	Priority Required
A	Maps domain to IPv4 address	192.0.2.1	لا
AAAA	Maps domain to IPv6 address	2001:0db8::1	لا
CNAME	Creates alias to another domain	example.com	لا
MX	Mail server for domain	mail.example.com	نعم
TXT	Text record (SPF, DKIM, verification)	v=spf1 include:_spf.google.com ~all	لا
NS	Nameserver delegation	ns1.example.com	لا
SRV	Service location record	10 5060 sip.example.com	نعم
CAA	Certificate authority authorization	0 issue "letsencrypt.org"	لا

أفضل الممارسات

تشكيل TTL

الإنتاج (المستقر): 3600-86400 ثانية (1-24 ساعة)
قبل الهجرة: 300-600 ثانية (5-10 دقائق) - تخفيض TTL قبل التغييرات المخططة
التنمية: 300-1800 ثانية (5-30 دقيقة) للاختبار الأسرع

الأنماط المشتركة

النطاق الجذري (@): استخدام سجلات A/AAAA، وليس CNAME
النطاق الفرعي www: يمكن استخدام CNAME للإشارة إلى الجذر أو سجل A منفصل
البريد الإلكتروني (MX): يدرج دائماً حسب الأولوية، الرقم الأدنى = الأولوية الأعلى
اسم النطاق: لا يمكن أن يتعايش مع أنواع أخرى من السجلات لنفس الاسم

دال - الأمن

سجلات CAA: تحديد هيئات الاعتماد التي يمكنها إصدار الشهادات
SPF/DKIM/DMARC: حدد إعدادات التحقق من البريد الإلكتروني لمنع التزوير
عمليات المراجعة المنتظمة للحسابات: استعراض سجلات اسم النطاق على أساس فصلي، وحذف القيود غير المستخدمة

معالجة الأخطاء

الأخطاء الشائعة

رمز الحالة	خطأ	الحل
400	اسم النطاق غير صحيح	كفالة اتباع النطاق لاتفاقيات التسمية في نظام أسماء النطاقات
400	يتطلب سجل MX أولوية	تشمل `priority` حقل لسجلات MX و SRV
401	رمز API غير صحيح	شكل رمز التحقق (يجب أن يبدأ بالحرف `vps_`)
403	عدم وجود إذن	إنشاء رمز جديد مع المطلوب `dns:*` الإذن
404	لم يُعثر على المنطقة/السجل	التحقق من UUID والتأكد من أن المورد ينتمي إلى حسابك

مثال على استجابة الخطأ

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

VPS.org API

واجهة برمجة تطبيقات إدارة نظام أسماء النطاقات (DNS)

ملخص

البنية التحتية لخواديم الأسماء

السمات الرئيسية

المصادقة

مثال

عرض جميع نطاقات نظام أسماء النطاقات (DNS)

معلمات الاستعلام

مثال على الطلب

مثال على الاستجابة

حقول الاستجابة

رموز حالة الاستجابة

احصل على تفاصيل منطقة DNS

معلمات المسار

مثال على الاستجابة

رموز حالة الاستجابة

إنشاء منطقة DNS

معلمات نص الطلب

مثال على الطلب

مثال على الاستجابة

رموز حالة الاستجابة

حذف منطقة DNS

معلمات المسار

رموز حالة الاستجابة

قائمة سجلات DNS في المنطقة

معلمات المسار

مثال على الطلب

مثال على الاستجابة

إنشاء سجل DNS في المنطقة

معلمات نص الطلب

مثال على الطلب

رموز حالة الاستجابة

إدارة سجلات DNS (الوصول المباشر)

العمليات المتاحة

بارامترات الاستفسار (لطلب /api/v1/dns-records/)

مثال: تحديث تاريخ التشغيل لسجل

Supported DNS Record Types

أفضل الممارسات

تشكيل TTL

الأنماط المشتركة

دال - الأمن

معالجة الأخطاء

الأخطاء الشائعة

مثال على استجابة الخطأ

اختبار تغييرات DNS

التحقق من نشر السجل

استخدام الأدوات الإلكترونية