REST API /api/v1
HTTPS · JSON UTF-8 · CORS. Base URL: https://api.vnwho.com/api/v1 (dev: http://localhost:3000/api/v1).
Xác thực & Rate limit
Gửi khóa qua header X-API-Key (do admin cấp). Header phản hồi: X-RateLimit-Limit/Remaining/Reset, kèm Retry-After khi 429.
| Tier | Giới hạn | Khóa |
|---|---|---|
| Public | 10 req/phút (theo IP) | không cần |
| Partner | 300 req/phút (theo key) | bắt buộc — mở khóa /whois/bulk |
Endpoints
GET /whois?domain=— WHOIS đầy đủ:status,data{registrant,registrar,nameservers,dates,domainStatus,dnssec},cached,backendsTried.GET /domain/check?domain=— khả dụng nhanh:available,premium; quy tắc.vnreserved/auction.POST /whois/bulk— ≤20 domain, tier Partner. Body{ "domains": [...] }.
Mã lỗi
| HTTP | code | Ý nghĩa |
|---|---|---|
| 400 | invalid_input / invalid_domain | tham số sai/thiếu |
| 401 | unauthorized | API key sai/thu hồi |
| 403 | forbidden | cần tier Partner (bulk) |
| 429 | rate_limited | vượt giới hạn — đợi Retry-After |
| 503 | registry_unavailable | nguồn WHOIS tạm lỗi |
Code mẫu
cURL
# WHOIS đầy đủ
curl -s "https://api.vnwho.com/api/v1/whois?domain=hvn.vn" \
-H "X-API-Key: YOUR_KEY"
# Kiểm tra khả dụng
curl -s "https://api.vnwho.com/api/v1/domain/check?domain=shophoa.vn"
# Bulk (Partner, <=20 domain)
curl -s -X POST "https://api.vnwho.com/api/v1/whois/bulk" \
-H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
-d '{"domains":["hvn.vn","shophoa.vn"]}'Node.js
// Node 18+ (fetch sẵn có) — tự retry khi 429 theo Retry-After
async function whois(domain) {
const url = 'https://api.vnwho.com/api/v1/whois?domain=' + encodeURIComponent(domain);
for (let attempt = 0; attempt < 4; attempt++) {
const res = await fetch(url, { headers: { 'X-API-Key': process.env.VNWHO_KEY } });
if (res.status === 429) {
const wait = Number(res.headers.get('Retry-After') || 1);
await new Promise((r) => setTimeout(r, wait * 1000));
continue;
}
if (!res.ok) throw new Error((await res.json()).code);
return res.json();
}
throw new Error('rate_limited');
}Python
import os, time, requests
def whois(domain):
url = "https://api.vnwho.com/api/v1/whois"
headers = {"X-API-Key": os.environ["VNWHO_KEY"]}
for _ in range(4):
r = requests.get(url, params={"domain": domain}, headers=headers)
if r.status_code == 429:
time.sleep(int(r.headers.get("Retry-After", 1)))
continue
r.raise_for_status()
return r.json()
raise RuntimeError("rate_limited")PHP
<?php
function whois($domain) {
$url = "https://api.vnwho.com/api/v1/whois?domain=" . urlencode($domain);
for ($i = 0; $i < 4; $i++) {
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: " . getenv("VNWHO_KEY")]);
$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($code === 429) { sleep(1); continue; }
return json_decode($body, true);
}
throw new Exception("rate_limited");
}