Add architecture docs and Go microservice to tech stack

2026-02-27 09:57:39 +00:00 · 2026-02-24 13:47:17 -05:00
parent 9a80accaf9
commit f49bdb7099
3 changed files with 219 additions and 1 deletions
--- a/docs/api-spec.md
+++ b/docs/api-spec.md
@@ -0,0 +1,135 @@
+# 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 |