VPS.org API

Documentació API REST

API de gestió de DNS

Gestioneu les zones i els registres DNS de manera programàtica per als vostres dominis.

Punts finals 4 punts finals
Camí base /api/v1/dns-zones
Autenticació Es requereix Beer Token

Visió general

The DNS API provides full management of DNS zones and records. All zones are hosted on VPS.org's authoritative nameservers with automatic BIND9 zone file generation and deployment.

Servidor de noms Infraestructura

Funcionalitats de tecla

Autenticació

Totes les sol· licituds de l' API de DNS requereix autenticació de fitxa d' a Bearer. Genera fitxes API del vostre tauler de comptes a /account/developers/ amb els següents permisos:

Exemple

Authorization: Bearer vps_abc123def456...
Important: Les fitxes de l' API només es mostren una vegada durant la creació. Emmagatzema- les amb seguretat. Si perdeu una fitxa, heu de generar- ne una de nova.
ACONSEGUEIX /api/v1/dns-zones/

Llista totes les zones DNS

Recupera una llista paginada de totes les zones DNS que pertanyin per l' usuari autenticat. Permet filtrar per nom de domini.

Paràmetres de consulta

Paràmetre Tipus Obligatori Descripció
domain string No Filter zones by exact domain name (e.g., example.com)

Exemple de sol·licitud

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

Exemple de resposta

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

Camps de resposta

Camp Tipus Descripció
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

Codis d'estat de resposta

200 Successfully retrieved DNS zones list
401 Unauthorized - Invalid or missing API token
403 Forbidden - Token lacks dns:list permission
ACONSEGUEIX /api/v1/dns-zones/{uuid}/

Obtén els detalls de la zona DNS

Recupera informació detallada sobre una zona DNS específica, incloent tots els registres.

Paràmetres de ruta

Paràmetre Tipus Obligatori Descripció
uuid string Sí Unique zone identifier

Exemple de resposta

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

Codis d'estat de resposta

200 Successfully retrieved zone details
404 Zone not found or not owned by user
POST /api/v1/dns-zones/

Crea una Zona DNS

Create a new DNS zone for a domain. The zone will be immediately deployed to VPS.org nameservers.

Paràmetres del cos de la sol·licitud

Paràmetre Tipus Obligatori Descripció
domain string Sí Domain name (e.g., example.com)

Exemple de sol·licitud

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

Exemple de resposta

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

Codis d'estat de resposta

201 DNS zone created successfully
400 Bad Request - Invalid domain name or zone already exists
403 Forbidden - Token lacks dns:create permission
ELIMINAR /api/v1/dns-zones/{uuid}/

Elimina la zona DNS

Elimina permanentment una zona DNS i tots els registres associats. Aquesta acció no es pot desfer.

Paràmetres de ruta

Paràmetre Tipus Obligatori Descripció
uuid string Sí Unique zone identifier

Codis d'estat de resposta

204 Zone deleted successfully (no response body)
403 Forbidden - Token lacks dns:delete permission
404 Zone not found
ACONSEGUEIX /api/v1/dns-zones/{uuid}/records/

Llista els registres DNS a la Zona

Recupera tots els registres DNS per a una zona específica.

Paràmetres de ruta

Paràmetre Tipus Obligatori Descripció
uuid string Sí Zone UUID

Exemple de sol·licitud

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

Exemple de resposta

[
  {
    "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 registre DNS a la Zona

Afegeix un nou registre DNS a una zona específica (re la ruta controlada).

Paràmetres del cos de la sol·licitud

Paràmetre Tipus Obligatori Descripció
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)

Exemple de sol·licitud

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

Codis d'estat de resposta

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

Gestiona els registres DNS (Expressió l' accés)

Operacions embarcades completes en els registres DNS individuals utilitzant el registre de l'UUID.

Operacions disponibles

Paràmetres de consulta (per obtenir / api/ v1/ dns-records /)

Parameter Tipus Descripció
zone string Filter records by zone UUID
record_type string Filter by record type (A, AAAA, MX, etc.)

Exemple: Actualitza el TTL d' un registre

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

Tipus 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

Millors exercicis

Configuració TTL

Patrons comuns

Seguretat

Gestió d' errors

Errors comuns

Codi d'estat Error Solució
400 Nom de domini no vàlid S' assegura que el domini segueix les convencions de nom DNS
400 El registre MX requereix prioritat Inclou priority camp per a registres MX i SRV
401 Testimoni d' API no vàlid Comprova el format de testimoni (ha d' iniciar amb vps_)
403 Falta permís Genera un testimoni nou amb requerit dns:* Permisos
404 No s' ha trobat el Zones/record Verifiqueu que el recurs UUID i assegureu- vos que pertany al vostre compte

Exemple de resposta d' error

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

S' estan provant els canvis DNS

Verifica la propietat del registre

# 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

Usar les eines en línia