API Reference

REST API for DNS testing with asynchronous task processing.

🔍 Interactive Documentation

Local Testing (requires server running):

• Swagger UI: http://localhost:5000/docs - Interactive API documentation with "Try it out" functionality

OpenAPI Specifications:

• Source: internal/api/docs/swagger.yaml and swagger.json (generated by swaggo)
• Documentation: docs/openapi.yaml (symlink for GitHub)
• Website: Synced to website/static/ by sync-docs.sh script

Online Viewer:

• Petstore Swagger Viewer - View and test the published spec

---

Quick Start

Submit → Poll → Results

# 1. Submit with explicit DNS server
curl -X POST http://localhost:5000/dns-lookup \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "qtype": "A",
    "dns_servers": [
      {"target": "udp://8.8.8.8:53"}
    ]
  }'
# → {"task_id":"abc123","message":"DNS lookup enqueued"}

# 2. Poll (recommended interval: 1-2 seconds)
curl http://localhost:5000/tasks/abc123
# → {"task_status":"SUCCESS","task_result":{...}}

Note: The dns_servers field is optional. If omitted, the API uses servers configured in conf/config.yaml. See Configuration for details.

For detailed request/response schemas, error codes, and interactive testing, see the Swagger UI.

---

Endpoints Summary

Method	Path	Description	Rate Limited
POST	/dns-lookup	Submit DNS lookup	✅
POST	/reverse-lookup	Submit PTR lookup	✅
GET	/tasks/{taskID}	Get task results	❌
GET	/health	Health check	❌
GET	/metrics	Prometheus metrics	❌