mirror of
https://github.com/DevVoxel/VectorDNS.git
synced 2026-02-27 05:47:38 +00:00
136 lines
2.3 KiB
Markdown
136 lines
2.3 KiB
Markdown
# Go DNS API Specification
|
|
|
|
Base URL: `https://<vps-host>/api/v1`
|
|
|
|
All requests require the header `X-API-Key: <shared-secret>`.
|
|
|
|
---
|
|
|
|
## Endpoints
|
|
|
|
### `POST /dns/lookup`
|
|
|
|
Resolve DNS records for a domain.
|
|
|
|
**Request:**
|
|
|
|
```json
|
|
{
|
|
"domain": "example.com",
|
|
"types": ["A", "AAAA", "MX", "TXT", "NS", "CNAME", "SOA", "CAA", "SRV"],
|
|
"nameserver": "8.8.8.8"
|
|
}
|
|
```
|
|
|
|
- `domain` (required): The domain to query.
|
|
- `types` (optional): Record types to query. Defaults to all supported types.
|
|
- `nameserver` (optional): 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 resolvers.
|
|
|
|
**Request:**
|
|
|
|
```json
|
|
{
|
|
"domain": "example.com",
|
|
"type": "A",
|
|
"resolvers": ["8.8.8.8", "1.1.1.1", "9.9.9.9"]
|
|
}
|
|
```
|
|
|
|
- `resolvers` (optional): 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.
|
|
|
|
**Request:**
|
|
|
|
```json
|
|
{
|
|
"domain": "example.com"
|
|
}
|
|
```
|
|
|
|
**Response (200):**
|
|
|
|
```json
|
|
{
|
|
"domain": "example.com",
|
|
"dnssec": true,
|
|
"chain_valid": true,
|
|
"details": "RRSIG verified for A record"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `GET /health`
|
|
|
|
Health check. No authentication required.
|
|
|
|
**Response (200):**
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"version": "0.1.0"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Error Responses
|
|
|
|
All errors follow this format:
|
|
|
|
```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 |
|