mirror of
https://github.com/DevVoxel/vectordns-server.git
synced 2026-02-27 01:40:12 +00:00
156 lines
3.0 KiB
Markdown
156 lines
3.0 KiB
Markdown
# API Reference
|
|
|
|
Complete reference for the VectorDNS Go server REST API.
|
|
|
|
## Base URL & Authentication
|
|
|
|
**Base URL:** `https://<your-vps-host>/api/v1`
|
|
|
|
All requests (except `/health`) require an API key header:
|
|
|
|
```
|
|
X-API-Key: <your-shared-secret>
|
|
```
|
|
|
|
Set `API_KEY` in your server environment to enable authentication. If left empty, auth is disabled (not recommended for production).
|
|
|
|
---
|
|
|
|
## Endpoints
|
|
|
|
### `POST /dns/lookup`
|
|
|
|
Resolve DNS records for a domain. Query one or more record types in a single request.
|
|
|
|
**Request:**
|
|
|
|
```json
|
|
{
|
|
"domain": "example.com",
|
|
"types": ["A", "AAAA", "MX", "TXT", "NS", "CNAME", "SOA", "CAA", "SRV"],
|
|
"nameserver": "8.8.8.8"
|
|
}
|
|
```
|
|
|
|
| Field | Required | Description |
|
|
|---|---|---|
|
|
| `domain` | Yes | The domain to query. |
|
|
| `types` | No | Record types to query. Defaults to all 9 supported types if omitted. |
|
|
| `nameserver` | No | Specific nameserver to query. Defaults to system resolver. |
|
|
|
|
**Response (200):**
|
|
|
|
```json
|
|
{
|
|
"domain": "example.com",
|
|
"nameserver": "8.8.8.8",
|
|
"records": {
|
|
"A": [{ "value": "93.184.216.34", "ttl": 300 }],
|
|
"MX": [{ "value": "mail.example.com", "priority": 10, "ttl": 3600 }]
|
|
},
|
|
"query_time_ms": 12
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `POST /dns/propagation`
|
|
|
|
Check DNS propagation across multiple public resolvers. Queries resolvers in parallel and compares results.
|
|
|
|
**Request:**
|
|
|
|
```json
|
|
{
|
|
"domain": "example.com",
|
|
"type": "A",
|
|
"resolvers": ["8.8.8.8", "1.1.1.1", "9.9.9.9"]
|
|
}
|
|
```
|
|
|
|
| Field | Required | Description |
|
|
|---|---|---|
|
|
| `domain` | Yes | The domain to check. |
|
|
| `type` | Yes | The record type to check (e.g. `A`, `MX`). |
|
|
| `resolvers` | No | List of resolver IPs. Defaults to a built-in list of public resolvers. |
|
|
|
|
**Response (200):**
|
|
|
|
```json
|
|
{
|
|
"domain": "example.com",
|
|
"type": "A",
|
|
"results": [
|
|
{ "resolver": "8.8.8.8", "values": ["93.184.216.34"], "ttl": 300 },
|
|
{ "resolver": "1.1.1.1", "values": ["93.184.216.34"], "ttl": 280 },
|
|
{ "resolver": "9.9.9.9", "values": ["93.184.216.34"], "ttl": 295 }
|
|
],
|
|
"consistent": true
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `POST /dns/validate`
|
|
|
|
DNSSEC validation for a domain. Checks the AD flag and verifies the signature chain.
|
|
|
|
**Request:**
|
|
|
|
```json
|
|
{
|
|
"domain": "example.com"
|
|
}
|
|
```
|
|
|
|
| Field | Required | Description |
|
|
|---|---|---|
|
|
| `domain` | Yes | The domain to validate. |
|
|
|
|
**Response (200):**
|
|
|
|
```json
|
|
{
|
|
"domain": "example.com",
|
|
"dnssec": true,
|
|
"chain_valid": true,
|
|
"details": "RRSIG verified for A record"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `GET /health`
|
|
|
|
Health check. No authentication required. Use this for uptime monitoring.
|
|
|
|
**Response (200):**
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"version": "0.1.0"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Error Responses
|
|
|
|
All errors return a consistent JSON body:
|
|
|
|
```json
|
|
{
|
|
"error": "invalid domain",
|
|
"code": "INVALID_DOMAIN"
|
|
}
|
|
```
|
|
|
|
| HTTP Status | Code | Description |
|
|
|---|---|---|
|
|
| 400 | `INVALID_DOMAIN` | Malformed or missing domain |
|
|
| 400 | `INVALID_TYPE` | Unsupported record type |
|
|
| 401 | `UNAUTHORIZED` | Missing or invalid API key |
|
|
| 500 | `DNS_ERROR` | Upstream DNS query failed |
|
|
| 500 | `INTERNAL` | Unexpected server error |
|