bindcar 0.6.0

HTTP REST API for managing BIND9 zones via rndc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

# API Reference

bindcar provides a REST API for managing BIND9 zones. All endpoints return JSON responses and require authentication (except health checks).

## Base URL

```
http://localhost:8080/api/v1
```

## Authentication

All API endpoints (except `/health` and `/ready`) require Bearer token authentication:

```bash
curl -H "Authorization: Bearer <token>" http://localhost:8080/api/v1/zones
```

In Kubernetes, use the ServiceAccount token:

```bash
TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)
curl -H "Authorization: Bearer $TOKEN" http://bindcar:8080/api/v1/zones
```

## Request/Response Flow

```mermaid
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](./api-health.md#health-check) - Service health
- [GET /api/v1/ready](./api-health.md#readiness-check) - Service readiness
- [GET /api/v1/server/status](./api-health.md#server-status) - BIND9 status

### Zone Management

- [POST /api/v1/zones](./api-zones.md#create-zone) - Create new zone
- [GET /api/v1/zones](./api-zones.md#list-zones) - List all zones
- [GET /api/v1/zones/{name}](./api-zones.md#get-zone) - Get zone information
- [DELETE /api/v1/zones/{name}](./api-zones.md#delete-zone) - Delete zone
- [POST /api/v1/zones/{name}/reload](./api-zones.md#reload-zone) - Reload zone
- [GET /api/v1/zones/{name}/status](./api-zones.md#zone-status) - Get zone status
- [POST /api/v1/zones/{name}/freeze](./api-zones.md#freeze-zone) - Freeze zone (disable updates)
- [POST /api/v1/zones/{name}/thaw](./api-zones.md#thaw-zone) - Thaw zone (enable updates)
- [POST /api/v1/zones/{name}/notify](./api-zones.md#notify-secondaries) - Notify secondary servers

### DNS Record Management

- [POST /api/v1/zones/{name}/records](./api-records.md#add-record) - Add individual record
- [DELETE /api/v1/zones/{name}/records](./api-records.md#remove-record) - Remove individual record
- [PUT /api/v1/zones/{name}/records](./api-records.md#update-record) - Update individual record

## Interactive API Documentation

bindcar includes a Swagger UI for interactive API exploration:

```
http://localhost:8080/api/v1/docs
```

The OpenAPI specification is available at:

```
http://localhost:8080/api/v1/openapi.json
```