DNS 관리 API

개요

DNS API는 DNS 영역과 레코드의 완전한 관리를 제공합니다. 모든 영역은 자동 BIND9 영역 파일 생성 및 배포와 함께 VPS.org의 권위있는 네임서버에 호스팅됩니다.

네임서버 인프라

ns1.vps.org (38.248.6.195) - DNSSEC 인라인 서명을 사용하는 기본 마스터
ns2.vps.org (38.248.6.196) - 보조 슬레이브
ns3.vps.org (38.248.6.197) - 보조 슬레이브

주요 기능

자동 BIND9 영역 파일 생성 및 배포
TSIG 인증을 통한 영역 전송(마스터-슬레이브 복제)
모든 주요 DNS 레코드 유형 지원(A, AAAA, CNAME, MX, TXT, NS, SRV, CAA)
도메인 이름 필터링 및 UUID 기반 영역 식별
영역별 레코드 관리를 위한 중첩된 경로

입증

모든 DNS API 요청에는 베어러 토큰 인증이 필요합니다. 계정 대시보드에서 API 토큰 생성 /account/developers/ 다음과 같은 권한으로:

dns:list - DNS 영역 및 레코드 보기
dns:create - 새로운 영역 및 레코드 생성
dns:update - 기존 영역 및 레코드 수정
dns:delete - 영역 및 레코드 삭제
dns:* - 완전한 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 레코드 관리(직접 액세스)

레코드 UUID를 사용하여 개별 DNS 레코드에 대한 전체 CRUD 작업.

사용 가능한 작업

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

쿼리 매개변수 (GET /api/v1/dns-records/에 대해)

Parameter	유형	설명
`zone`	string	Filter records by zone UUID
`record_type`	string	Filter by record type (A, AAAA, MX, etc.)

예: 레코드의 TTL 업데이트

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분)의 빠른 테스트

일반 패턴

루트 도메인 (@): CNAME이 아닌 A/AAAA 레코드 사용
www 하위 도메인: 루트 또는 분리된 A 레코드에 대한 CNAME 포인팅을 사용할 수 있습니다.
전자 우편 (MX): 항상 우선순위 포함, 낮은 숫자 = 높은 우선순위
CNAME: 같은 이름의 다른 레코드 유형과 공존할 수 없음

보안

CAA 기록: 인증서를 발급할 수 있는 CA 지정
SPF/DKIM/DMARC: 로그인 스푸핑을 방지하기 위해 이메일 인증 구성
정기 감사: 분기별로 DNS 레코드 검토, 사용되지 않는 항목 제거

오류 처리

일반적인 오류

상태 코드	오류	솔루션
400	잘못된 도메인 이름	도메인이 DNS 명명 규칙을 따르도록 보장
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 레코드 관리(직접 액세스)

사용 가능한 작업

쿼리 매개변수 (GET /api/v1/dns-records/에 대해)

예: 레코드의 TTL 업데이트

Supported DNS Record Types

모범 사례

TTL 설정

일반 패턴

보안

오류 처리

일반적인 오류

예시 오류 응답

DNS 변경 테스트

레코드 전파 확인

온라인 도구 사용