API Reference¶
bindcar provides a REST API for managing BIND9 zones. All endpoints return JSON responses and require authentication (except health checks).
Base URL¶
Authentication¶
All API endpoints (except /health and /ready) require Bearer token authentication:
In Kubernetes, use the ServiceAccount token:
TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)
curl -H "Authorization: Bearer $TOKEN" http://bindcar:8080/api/v1/zones
Request/Response Flow¶
sequenceDiagram
participant Client
participant API as bindcar API
participant BIND9
participant FS as File System
Client->>API: HTTP Request + Bearer Token
API->>API: Validate Token
alt Invalid Token
API-->>Client: 401 Unauthorized
end
API->>FS: Write Zone File
FS-->>API: Success
API->>BIND9: Execute rndc command
BIND9-->>API: Command Output
API-->>Client: JSON Response
Common Response Codes¶
| Code | Description |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request - Invalid input |
| 401 | Unauthorized - Missing or invalid token |
| 404 | Not Found - Zone doesn't exist |
| 500 | Internal Server Error |
| 500 | Bad Gateway - RNDC command failed |
Endpoints Overview¶
Health & Monitoring¶
- GET /api/v1/health - Service health
- GET /api/v1/ready - Service readiness
- GET /api/v1/server/status - BIND9 status
Zone Management¶
- POST /api/v1/zones - Create new zone
- GET /api/v1/zones - List all zones
- GET /api/v1/zones/{name} - Get zone information
- DELETE /api/v1/zones/{name} - Delete zone
- POST /api/v1/zones/{name}/reload - Reload zone
- GET /api/v1/zones/{name}/status - Get zone status
- POST /api/v1/zones/{name}/freeze - Freeze zone (disable updates)
- POST /api/v1/zones/{name}/thaw - Thaw zone (enable updates)
- POST /api/v1/zones/{name}/notify - Notify secondary servers
DNS Record Management¶
- POST /api/v1/zones/{name}/records - Add individual record
- DELETE /api/v1/zones/{name}/records - Remove individual record
- PUT /api/v1/zones/{name}/records - Update individual record
Interactive API Documentation¶
bindcar includes a Swagger UI for interactive API exploration:
The OpenAPI specification is available at: