API di gestione DNS

Panoramica

L'API DNS fornisce la gestione completa delle zone e dei record DNS. Tutte le zone sono ospitate sui nameserver autorevoli di VPS.org con generazione e distribuzione automatica di file BIND9 zone.

Nameserver Infrastructure

ns1.vps.org (38.248.6.195) - Master primario con firma in linea DNSSEC
ns2.vps.org (38.248.6.196) - Schiavo secondario
ns3.vps.org (38.248.6.197) - Schiavo secondario

Caratteristiche chiave

Generazione e distribuzione automatica dei file di zona BIND9
Trasferimenti di zone tramite autenticazione TSIG (replica master-slave)
Supporto per tutti i principali tipi di record DNS (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA)
Filtraggio dei nomi di dominio e identificazione della zona basata su UUID
Itinerari nidificati per la gestione dei record specifici delle zone

Autenticazione

Tutte le richieste di API DNS richiedono l'autenticazione del token Bearer. Generare i token API dal cruscotto dell'account a /account/developers/ con i seguenti permessi:

dns:list - Visualizza zone e record DNS
dns:create - Crea nuove zone e record
dns:update - Modificare le zone e i registri esistenti
dns:delete - Cancellare zone e registrazioni
dns:* - Accesso completo alla gestione DNS

Esempio

Authorization: Bearer vps_abc123def456...

Importante: I token API vengono mostrati solo una volta durante la creazione. Memorizzali in modo sicuro. Se perdi un token, devi generarne uno nuovo.

OTTENERE /api/v1/dns-zones/

Elenca tutte le zone DNS

Recuperare un elenco paginato di tutte le zone DNS di proprietà dell'utente autenticato. Supporta il filtraggio per nome di dominio.

Parametri di query

Parametro	Tipo	Necessario	Designazione delle merci
`domain`	string	No.	Filter zones by exact domain name (e.g., `example.com`)

Richiesta di esempio

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

Esempio di risposta

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

Campi di risposta

Campo	Tipo	Designazione delle merci
`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

Codici di stato della risposta

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

OTTENERE /api/v1/dns-zones/{uuid}/

Ottieni i dettagli della zona DNS

Recuperare informazioni dettagliate su una zona DNS specifica, compresi tutti i record.

Parametri del percorso

Parametro	Tipo	Necessario	Designazione delle merci
`uuid`	string	SÌ	Unique zone identifier

Esempio di risposta

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

Codici di stato della risposta

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

POST /api/v1/dns-zones/

Crea zona DNS

Crea una nuova zona DNS per un dominio. La zona sarà immediatamente distribuita a VPS.org nameserver.

Parametri del corpo della richiesta

Parametro	Tipo	Necessario	Designazione delle merci
`domain`	string	SÌ	Domain name (e.g., `example.com`)

Richiesta di esempio

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

Esempio di risposta

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

Codici di stato della risposta

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

ELIMINARE /api/v1/dns-zones/{uuid}/

Elimina zona DNS

Elimina definitivamente una zona DNS e tutti i record associati. Questa azione non può essere annullata.

Parametri del percorso

Parametro	Tipo	Necessario	Designazione delle merci
`uuid`	string	SÌ	Unique zone identifier

Codici di stato della risposta

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

OTTENERE /api/v1/dns-zones/{uuid}/records/

Elenca DNS Records in Zone

Recuperare tutti i record DNS per una zona specifica (percorso segnalato).

Parametri del percorso

Parametro	Tipo	Necessario	Designazione delle merci
`uuid`	string	SÌ	Zone UUID

Richiesta di esempio

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

Esempio di risposta

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

POST /api/v1/dns-zones/{uuid}/records/

Crea record DNS in zona

Aggiungi un nuovo record DNS a una zona specifica (percorso nidificato).

Parametri del corpo della richiesta

Parametro	Tipo	Necessario	Designazione delle merci
`record_type`	string	SÌ	Record type: A, AAAA, CNAME, MX, TXT, NS, SRV, CAA
`name`	string	SÌ	Record name (`@` for root, subdomain, or FQDN)
`value`	string	SÌ	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)

Richiesta di esempio

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

Codici di stato della risposta

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

Gestisci DNS Records (Direct Access)

Operazioni CRUD complete su singoli record DNS utilizzando UUID record.

Operazioni disponibili

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

Parametri di interrogazione (per GET /api/v1/dns-records/)

Parameter	Tipo	Designazione delle merci
`zone`	string	Filter records by zone UUID
`record_type`	string	Filter by record type (A, AAAA, MX, etc.)

Esempio: Aggiorna TTL di un record

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

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

Migliori pratiche

Configurazione TTL

Produzione (stabile): 3600-86400 secondi (1-24 ore)
Prima della migrazione: 300-600 secondi (5-10 minuti) - Abbassare TTL prima delle modifiche previste
Sviluppo: 300-1800 secondi (5-30 minuti) per un test più veloce

Modelli comuni

Dominio radice (@): Utilizzare registrazioni A/AAAA, non CNAME
Sottodominio www: Può usare CNAME puntando a root o separato Un record
Email (MX): Includi sempre priorità, numero inferiore = priorità più alta
CNAME: Impossibile coesistere con altri tipi di record per lo stesso nome

Sicurezza

CAA Records: Specificare quali CA possono rilasciare certificati
SPF/DKIM/DMARC: Configura l'autenticazione email per prevenire lo spoofing
Verifiche regolari: Recensione dei record DNS trimestrali, rimuovere le voci non utilizzate

Gestione degli errori

Errori comuni

Codice di stato	Errore	Soluzione
400	Nome di dominio non valido	Assicurarsi che il dominio segua le convenzioni di denominazione DNS
400	Il record MX richiede priorità	Includi `priority` campo per i record MX e SRV
401	Token API non valido	Controlla il formato token (deve iniziare con `vps_`)
403	Autorizzazione mancante	Genera nuovo token con richiesta `dns:*` autorizzazioni
404	Zona/registrazione non trovata	Verifica UUID e assicura che la risorsa appartenga al tuo account

Esempio di risposta all'errore

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

Verifica delle modifiche DNS

Verifica la propagazione della registrazione

# 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

Utilizzo di strumenti online

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

VPS.org API

API di gestione DNS

Panoramica

Nameserver Infrastructure

Caratteristiche chiave

Autenticazione

Esempio

Elenca tutte le zone DNS

Parametri di query

Richiesta di esempio

Esempio di risposta

Campi di risposta

Codici di stato della risposta

Ottieni i dettagli della zona DNS

Parametri del percorso

Esempio di risposta

Codici di stato della risposta

Crea zona DNS

Parametri del corpo della richiesta

Richiesta di esempio

Esempio di risposta

Codici di stato della risposta

Elimina zona DNS

Parametri del percorso

Codici di stato della risposta

Elenca DNS Records in Zone

Parametri del percorso

Richiesta di esempio

Esempio di risposta

Crea record DNS in zona

Parametri del corpo della richiesta

Richiesta di esempio

Codici di stato della risposta

Gestisci DNS Records (Direct Access)

Operazioni disponibili

Parametri di interrogazione (per GET /api/v1/dns-records/)

Esempio: Aggiorna TTL di un record

Supported DNS Record Types

Migliori pratiche

Configurazione TTL

Modelli comuni

Sicurezza

Gestione degli errori

Errori comuni

Esempio di risposta all'errore

Verifica delle modifiche DNS

Verifica la propagazione della registrazione

Utilizzo di strumenti online