API Referansı

Kimlik Doğrulama

Tüm API istekleri bir API anahtarı kullanarak kimlik doğrulaması gerektirir. Anahtarı Authorization başlığında Bearer token olarak geçirin. API anahtarı nxd_ öneki ile başlamalıdır.

Authorization: Bearer nxd_your_api_key_here

API güvenlik duvarı durumsuz çalışır – her istek bağımsız olarak doğrulanır. Oturum veya çerez kullanılmaz.

API anahtarınızı gizli tutun. İstemci tarafı kodunda, herkese açık depolarda veya URL'lerde paylaşmayın. Bir anahtar ele geçirilirse hemen iptal edin ve yenisini oluşturun.

Kimlik Doğrulama Hataları

Yanıt Formatı

Tüm yanıtlar JSON formatındadır. Başarılı yanıtlar aşağıdaki yapıya sahiptir:

Tekil Kaynak

{
    "status": "success",
    "data": {
        "id": 42,
        "public_id": "xK9mP2",
        "name": "example.com",
        ...
    }
}

Sayfalanmış Liste

{
    "status": "success",
    "data": [ ... ],
    "meta": {
        "total": 150,
        "page": 1,
        "per_page": 25,
        "last_page": 6
    }
}

Hata Yanıtı

{
    "status": "error",
    "error": {
        "code": "validation_error",
        "message": "Validation failed.",
        "details": {
            "name": ["Domain name is required."]
        }
    }
}

Genel Kimlikler

Her kaynak, URL yollarında kullanılan opak bir id (örneğin xK9mQ2) ile tanımlanır. Ham sayısal veritabanı kimlikleri asla açığa çıkarılmaz veya kabul edilmez.

Sayfalama

Sayfalanmış sonuçlar döndüren liste uç noktaları aşağıdaki sorgu parametrelerini kabul eder:

Bölgeler

DNS bölgelerini yönetin. Okuma işlemleri için zones.read, yazma işlemleri için zones.write gerektirir.

GET /v1/zones

Kimliği doğrulanmış kullanıcının tüm bölgelerini listeler.

Sorgu parametreleri

• search – bölgeleri ada göre filtrele
• page, per_page – sayfalama

Yanıt alanları

Döndürülen alanlar: id, name, type (master/slave), status, ns_group, created_at, updated_at

GET /v1/zones/{id}

SOA verileri, ad sunucuları ve kayıt sayısı dahil belirli bir bölge hakkında ayrıntılı bilgi alır.

Ek yanıt alanları

records_count, soa (primary_ns, admin_email, serial, refresh, retry, expire, minimum), nameservers (dizi), ns_group (id, slug, name)

POST /v1/zones

Yeni bir DNS bölgesi oluşturur. Kullanıcının vadesi geçmiş faturaları varsa bölge oluşturma engellenir.

İstek gövdesi (JSON)

{
    "name": "example.com",
    "type": "master",
    "ns_group_id": 1,
    "master_ip": ""
}

• name (zorunlu) – alan adı
• type – "master" (varsayılan) veya "slave"
• ns_group – bölgenin atanacağı NS grubu (isteğe bağlı, belirtilmezse varsayılan kullanılır)
• master_ip – slave bölgeler için zorunlu; geçerli bir IP adresi olmalıdır

201 Created ile bölge nesnesini döndürür.

DELETE /v1/zones/{id}

Bir bölgeyi ve tüm kayıtlarını siler.

Başarılı olduğunda 204 No Content döndürür.

GET /v1/zones/{id}/export

Bir bölgeyi BIND formatında veya yapılandırılmış JSON olarak dışa aktarır.

Sorgu parametreleri

• format – "bind" (varsayılan) BIND bölge dosyası metni döndürür; "json" ad, tür, içerik ve TTL ile yapılandırılmış bir kayıt dizisi döndürür

Kayıtlar

Bir bölge içindeki DNS kayıtlarını yönetin. Tüm kayıt uç noktaları bir bölge altında iç içe yerleştirilmiştir. Okuma işlemleri için records.read, yazma işlemleri için records.write gerektirir.

GET /v1/zones/{zoneId}/records

Bir bölgedeki tüm kayıtları listeler.

Sorgu parametreleri

• type – kayıt türüne göre filtrele (örn. A, CNAME, MX)
• name – kayıt adına göre filtrele (alt dize eşleşmesi)
• search – hem ad hem de içerikte ara

Yanıt alanları

id, name, type, content, ttl, disabled, fields (türe özgü ayrıştırılmış alanlar)

GET /v1/zones/{zoneId}/records/{recordId}

Kimliğine göre tek bir kayıt alır.

POST /v1/zones/{zoneId}/records

Yeni bir DNS kaydı oluşturur.

İstek gövdesi (JSON)

{
    "type": "A",
    "name": "www",
    "ttl": 3600,
    "content": "93.184.216.34"
}

• type (zorunlu) – kayıt türü (A, AAAA, CNAME, MX, TXT, SRV, CAA, NS, PTR, ALIAS, DNAME, DS, TLSA)
• name – bölgeye göre kayıt adı (varsayılan: bölge kökü için @)
• ttl – saniye cinsinden yaşam süresi (varsayılan: 3600)
• content – kayıt değeri (A/AAAA için IP, CNAME/NS/PTR için ana bilgisayar adı, TXT için metin, MX için posta sunucusu)

Türe özgü alanlar

• MX: priority (varsayılan: 10)
• SRV kaydı: priority, weight, port
• CAA: flags (varsayılan: 0), tag (varsayılan: "issue")
• DS kaydı: keytag, algorithm, digest_type
• TLSA kaydı: usage, selector, matching_type

201 Created ile kayıt nesnesini döndürür.

PUT /v1/zones/{zoneId}/records/{recordId}

Mevcut bir kaydı günceller. Yalnızca değiştirmek istediğiniz alanları ekleyin; atlanmış alanlar mevcut değerlerini korur.

{
    "content": "93.184.216.35",
    "ttl": 7200
}

Güncellenmiş kayıt nesnesiyle birlikte 200 OK döndürür. Not: kayıt kimliği, kaydın adı, türü ve içeriğinden hesaplandığı için güncelleme sonrasında değişebilir.

DELETE /v1/zones/{zoneId}/records/{recordId}

Bölgeden bir kaydı siler.

Başarılı olduğunda 204 No Content döndürür.

DNSSEC

Bölgeleriniz için DNSSEC'i yönetin. Durumu görüntülemek için zones.read, etkinleştirmek veya devre dışı bırakmak için zones.write gerektirir.

GET /v1/zones/{id}/dnssec

Anahtarlar ve DS kayıtları dahil bir bölgenin DNSSEC durumunu alır.

Yanıt alanları

enabled (boolean), keys (DNSKEY kayıtları dizisi), ds_records (kayıt şirketine eklenecek DS kayıtları dizisi)

POST /v1/zones/{id}/dnssec/enable

Bir bölge için DNSSEC'i etkinleştirir. İmzalama anahtarlarını otomatik olarak oluşturur.

Oluşturulan anahtarlar ve DS kayıtlarıyla birlikte DNSSEC durumunu döndürür.

POST /v1/zones/{id}/dnssec/disable

Bir bölge için DNSSEC'i devre dışı bırakır. Tüm imzalama anahtarlarını kaldırır.

{"enabled": false, "keys": [], "ds_records": []} döndürür.

NS Grupları

Kullanılabilir ad sunucusu gruplarını listeler. Bir bölge oluştururken grubun id değerini ns_group olarak kullanın. Bu uç noktayı geçerli herhangi bir API anahtarı okuyabilir.

GET /v1/ns-groups

Etkin ad sunucusu gruplarını listeler.

Grup başına yanıt alanları

id, name, slug

Hesap

Hesap bilgilerini görüntüleyin ve API anahtarlarını yönetin.

GET /v1/account

Abonelik ayrıntıları dahil mevcut hesap bilgilerini alır.

Yanıt alanları

Döndürülen alanlar: id (UUID), email, name, role, status, language, timezone, created_at

subscription – plan, billing_cycle, status, current_period_start, current_period_end alanlarına sahip nesne (abonelik yoksa null)

GET /v1/account/api-keys

Kimliği doğrulanmış kullanıcının tüm API anahtarlarını listeler.

Anahtar başına yanıt alanları

id, name, key_prefix (ilk 8 karakter), permissions (dizi), last_used_at, expires_at, created_at

POST /v1/account/api-keys

Yeni bir API anahtarı oluşturur.

İstek gövdesi (JSON)

{
    "name": "CI/CD Pipeline",
    "permissions": ["zones.read", "records.read", "records.write"],
    "expires_at": "2027-01-01"
}

• name (zorunlu) – okunabilir ad (en fazla 255 karakter)
• permissions (zorunlu) – izinler dizisi (en az bir tane gerekli): zones.read, zones.write, records.read, records.write, webhooks.read, webhooks.write
• expires_at – isteğe bağlı son kullanma tarihi (ISO 8601 veya YYYY-MM-DD); gelecekte olmalıdır

Yanıt, key alanında tam API anahtarını içerir. Tam anahtar yalnızca bu kez döndürülür. Güvenli bir şekilde saklayın.

Tam key değeri dahil anahtar ayrıntılarıyla birlikte 201 Created döndürür.

DELETE /v1/account/api-keys/{id}

Bir API anahtarını iptal eder (kalıcı olarak siler).

Başarılı olduğunda 204 No Content döndürür.

Faturalama

Abonelik, planlar ve faturaları görüntüleyin. Bu uç noktalar salt okunurdur.

GET /v1/billing/subscription

Mevcut abonelik ayrıntılarını alır. Aktif abonelik yoksa null döndürür.

Yanıt alanları

Döndürülen alanlar: id, plan, billing_cycle, status, current_period_start, current_period_end, created_at

GET /v1/billing/plans

Fiyatlandırma ve özelliklerle birlikte tüm mevcut planları listeler.

Plan başına yanıt alanları

id, name, slug, description, price_monthly, price_yearly, currency, max_domains, max_records, features (dizi)

GET /v1/billing/invoices

Kimliği doğrulanmış kullanıcının faturalarını listeler, en yeniler önce.

Sorgu parametreleri

• status – duruma göre filtrele (draft, issued, sent, void)
• page, per_page – sayfalama

GET /v1/billing/invoices/{id}

Bir faturayı <code>id</code> değeriyle alır.

Yanıt alanları

Döndürülen alanlar: id, number, status, amount (vergi dahil), net_amount (vergi hariç), tax_amount, tax_rate, currency, issued_at, created_at. Parasal değerler düz ondalık dizelerdir.

Webhooks

Bölge ve kayıt değişiklikleri hakkında gerçek zamanlı bildirim almak için giden webhook aboneliklerini yönetin. Okuma için webhooks.read, oluşturma, değiştirme veya silme için webhooks.write gerektirir.

GET /v1/webhooks

Kimliği doğrulanmış kullanıcının tüm webhook aboneliklerini listeler.

Webhook başına yanıt alanları

id, url, events (dizi), description, is_active, failure_count, last_triggered_at, created_at

POST /v1/webhooks

Bir webhook aboneliği oluşturur.

İstek gövdesi (JSON)

{
    "url": "https://example.com/webhook",
    "events": ["zone.created", "record.created"],
    "description": "Production webhook"
}

• url (zorunlu) – olay verilerini alacak HTTPS uç noktası
• events (zorunlu) – abone olunacak olay türleri dizisi
• description – isteğe bağlı okunabilir etiket

Yanıt, webhook imzalarını (HMAC) doğrulamak için bir secret içerir. Secret yalnızca bu sefer döndürülür. Güvenli bir yerde saklayın.

Webhook'un id ve secret değerleriyle 201 Created döndürür.

GET /v1/webhooks/{id}

Tek bir webhook aboneliğini en son teslimatlarıyla birlikte alır.

PUT /v1/webhooks/{id}

Bir webhook aboneliğini günceller. Yalnızca değiştirmek istediğiniz alanları ekleyin.

Güncellenmiş webhook nesnesiyle 200 OK döndürür.

DELETE /v1/webhooks/{id}

Bir webhook aboneliğini siler.

Başarılı olduğunda 204 No Content döndürür.

POST /v1/webhooks/{id}/test

Erişilebilirliği doğrulamak için webhook uç noktasına bir test olayı gönderir.

"type": "test" verisiyle bir test teslimatını kuyruğa alır.

Kullanılabilir olay türleri

Bu olay türlerinin herhangi bir kombinasyonuna abone olabilirsiniz:

zone.created, zone.deleted, record.created, record.updated, record.deleted, dnssec.enabled, dnssec.disabled, zone.health.problem, zone.health.resolved

Hata Kodları

Tüm hatalar, bir hata code dizesi ve okunabilir bir message ile tutarlı bir format izler.

Kod Örnekleri

Tüm örnekler curl kullanır. nxd_your_api_key yerine gerçek API anahtarınızı yazın.

Bölgelerinizi listeleyin

curl -s "https://api.nexdns.tech/v1/zones" \
    -H "Authorization: Bearer nxd_your_api_key"

Bölge oluşturun

curl -s -X POST "https://api.nexdns.tech/v1/zones" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"name": "example.com"}'

A kaydı ekleyin

curl -s -X POST "https://api.nexdns.tech/v1/zones/{zoneId}/records" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
        "type": "A",
        "name": "www",
        "ttl": 3600,
        "content": "93.184.216.34"
    }'

MX kaydı ekleyin

curl -s -X POST "https://api.nexdns.tech/v1/zones/{zoneId}/records" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
        "type": "MX",
        "name": "@",
        "ttl": 3600,
        "content": "mail.example.com",
        "priority": 10
    }'

Kaydı güncelleyin

curl -s -X PUT "https://api.nexdns.tech/v1/zones/{zoneId}/records/{recordId}" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"content": "93.184.216.35", "ttl": 7200}'

Kaydı silin

curl -s -X DELETE "https://api.nexdns.tech/v1/zones/{zoneId}/records/{recordId}" \
    -H "Authorization: Bearer nxd_your_api_key"

Bölgeyi dışa aktarın (BIND formatı)

curl -s "https://api.nexdns.tech/v1/zones/{zoneId}/export" \
    -H "Authorization: Bearer nxd_your_api_key"

DNSSEC'i etkinleştirin

curl -s -X POST "https://api.nexdns.tech/v1/zones/{zoneId}/dnssec/enable" \
    -H "Authorization: Bearer nxd_your_api_key"

API anahtarı oluşturun

curl -s -X POST "https://api.nexdns.tech/v1/account/api-keys" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Read-only key",
        "permissions": ["zones.read", "records.read"],
        "expires_at": "2027-12-31"
    }'

Hesap bilgilerini alın

curl -s "https://api.nexdns.tech/v1/account" \
    -H "Authorization: Bearer nxd_your_api_key"