dhcp-dns-manager/API_EXAMPLES.md

# API 接口测试示例

使用 curl 测试 API 接口

## 1. 登录获取 Session

```bash
curl -X POST http://localhost:8080/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin"
  }'
```

响应：
```json
{
  "session_id": "demo-session-id",
  "is_admin": true
}
```

---

## 2. 获取仪表盘数据

```bash
curl -X GET http://localhost:8080/api/dashboard \
  -H "X-Session-ID: demo-session-id"
```

---

## 3. DHCP 管理

### 获取活跃租约
```bash
curl -X GET http://localhost:8080/api/dhcp/leases \
  -H "X-Session-ID: demo-session-id"
```

### 获取静态绑定
```bash
curl -X GET http://localhost:8080/api/dhcp/bindings \
  -H "X-Session-ID: demo-session-id"
```

### 创建静态绑定
```bash
curl -X POST http://localhost:8080/api/dhcp/bindings \
  -H "X-Session-ID: demo-session-id" \
  -H "Content-Type: application/json" \
  -d '{
    "mac": "00:11:22:33:44:55",
    "ip": "192.168.1.100",
    "hostname": "my-server",
    "description": "我的服务器"
  }'
```

### 删除静态绑定
```bash
curl -X DELETE http://localhost:8080/api/dhcp/bindings/1 \
  -H "X-Session-ID: demo-session-id"
```

---

## 4. DNS 管理

### 获取 DNS 记录
```bash
curl -X GET http://localhost:8080/api/dns/records \
  -H "X-Session-ID: demo-session-id"
```

### 创建 A 记录
```bash
curl -X POST http://localhost:8080/api/dns/records \
  -H "X-Session-ID: demo-session-id" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test.example.com",
    "type": "A",
    "value": "192.168.1.100",
    "ttl": 300
  }'
```

### 创建 CNAME 记录
```bash
curl -X POST http://localhost:8080/api/dns/records \
  -H "X-Session-ID: demo-session-id" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "www.example.com",
    "type": "CNAME",
    "value": "example.com",
    "ttl": 3600
  }'
```

### 删除 DNS 记录
```bash
curl -X DELETE http://localhost:8080/api/dns/records/1 \
  -H "X-Session-ID: demo-session-id"
```

### 获取 DNS 查询日志
```bash
curl -X GET http://localhost:8080/api/dns/logs \
  -H "X-Session-ID: demo-session-id"
```

---

## 5. 系统管理

### 获取配置
```bash
curl -X GET http://localhost:8080/api/config \
  -H "X-Session-ID: demo-session-id"
```

### 更新配置
```bash
curl -X PUT http://localhost:8080/api/config \
  -H "X-Session-ID: demo-session-id" \
  -H "Content-Type: application/json" \
  -d '{
    "dhcp": {
      "enabled": true,
      "ip_pool_start": "192.168.1.50",
      "ip_pool_end": "192.168.1.250"
    }
  }'
```

---

## 6. 使用 Python 测试

```python
import requests

BASE_URL = "http://localhost:8080"

# 登录
login_resp = requests.post(f"{BASE_URL}/api/login", json={
    "username": "admin",
    "password": "admin"
})
session_id = login_resp.json()["session_id"]

headers = {"X-Session-ID": session_id}

# 获取仪表盘
dashboard = requests.get(f"{BASE_URL}/api/dashboard", headers=headers)
print("Dashboard:", dashboard.json())

# 创建 DNS 记录
create_resp = requests.post(f"{BASE_URL}/api/dns/records", 
    headers=headers, 
    json={
        "name": "test.local",
        "type": "A",
        "value": "192.168.1.100",
        "ttl": 300
    }
)
print("Create record:", create_resp.json())

# 获取 DNS 记录
records = requests.get(f"{BASE_URL}/api/dns/records", headers=headers)
print("DNS Records:", records.json())
```

---

## 7. 使用 Postman

导入以下集合作为快速开始：

```json
{
  "info": {
    "name": "DHCP DNS Manager API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Login",
      "request": {
        "method": "POST",
        "header": [{"key": "Content-Type", "value": "application/json"}],
        "url": "http://localhost:8080/api/login",
        "body": {
          "mode": "raw",
          "raw": "{\"username\":\"admin\",\"password\":\"admin\"}"
        }
      }
    },
    {
      "name": "Get Dashboard",
      "request": {
        "method": "GET",
        "header": [{"key": "X-Session-ID", "value": "{{session_id}}"}],
        "url": "http://localhost:8080/api/dashboard"
      }
    }
  ]
}
```

---

## 错误码说明

| 状态码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权（Session 无效） |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## 提示

1. 所有受保护的 API 都需要 `X-Session-ID` 请求头
2. Session ID 通过登录接口获取
3. 生产环境建议使用 HTTPS
4. 默认 Session 不会过期（开发中）