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.

TierGiới hạnKhóa
Public10 req/phút (theo IP)không cần
Partner300 req/phút (theo key)bắt buộc — mở khóa /whois/bulk

Endpoints

Mã lỗi

HTTPcodeÝ nghĩa
400invalid_input / invalid_domaintham số sai/thiếu
401unauthorizedAPI key sai/thu hồi
403forbiddencần tier Partner (bulk)
429rate_limitedvượt giới hạn — đợi Retry-After
503registry_unavailablenguồ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");
}