# 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 |