---

```markdown
# 📘 IoT API 接口文档

> 模块：`iot_api`  
> 作者：**anlicheng**  
> 创建时间：2023-12-24  
> 数据格式：`application/json`  
> 认证方式：内置 `API_TOKEN = "wv6fGyBhl*7@AsD9"`

---

## 🔐 通用请求头

| Header | 值 | 说明 |
|--------|----|------|
| Content-Type | application/json | 请求体格式 |
| Accept | application/json | 响应体格式 |

---

## 🧩 主机（Host）相关接口

### 1. 获取所有主机列表

**接口：**
```

GET /get_all_hosts

````

**参数：**
无

**返回示例：**
```json
{"result":
  [
    "uuid-1",
    "uuid-2",
    "uuid-3"
  ]
}
````
---

### 2. 通过 UUID 获取主机信息

**接口：**

```
GET /get_host_by_uuid?uuid=<uuid>
```

**参数：**

| 参数名  | 类型     | 必填 | 说明      |
| ---- | ------ | -- | ------- |
| uuid | string | ✅  | 主机 UUID |

**返回示例：(包含host的全部字段)**

```json
{
  "result": {
    "id": 1,
    "uuid": "uuid-1",
    "name": "HostA",
    "status": 1,
    "authorize_status": 1,
    "created_at": "2024-01-01T00:00:00Z"
  }
}
```

---

### 3. 通过主机 ID 获取主机信息

**接口：**

```
GET /get_host_by_id?host_id=<id>
```

**参数：**

| 参数名     | 类型      | 必填 | 说明    |
| ------- | ------- | -- | ----- |
| host_id | integer | ✅  | 主机 ID |

**返回示例：(包含host的全部字段)**

```json
{
  "result": {
    "id": 1,
    "uuid": "uuid-1",
    "name": "HostA",
    "authorize_status": 1
  }
}
```

---

### 4. 修改主机状态

**接口：**

```
POST /change_host_status
```

**请求体：**

```json
{
  "uuid": "uuid-1",
  "new_status": 1
}
```

**返回示例：**

```json
{
  "result": "ok"
}
```

---

### 5. 获取主机下的设备列表

**接口：**

```
GET /get_host_devices?host_id=<id>
```

**参数：**

| 参数名     | 类型      | 必填 | 说明    |
| ------- | ------- | -- | ----- |
| host_id | integer | ✅  | 主机 ID |

**返回示例：(包含device的全部字段)**

```json
{
  "result": [
    { "device_uuid": "dev-1", "status": 1 },
    { "device_uuid": "dev-2", "status": 0 }
  ]
}
```

---

## 🔧 设备（Device）相关接口

### 6. 获取设备详情

**接口：**

```
GET /get_device_by_uuid?device_uuid=<uuid>
```

**参数：**

| 参数名         | 类型     | 必填 | 说明      |
| ----------- | ------ | -- | ------- |
| device_uuid | string | ✅  | 设备 UUID |

**返回示例：(包含device的全部字段)**

```json
{
  "result": {
    "device_uuid": "dev-1",
    "type": "sensor",
    "status": 1
  }
}
```

---

### 7. 修改设备状态

**接口：**

```
POST /change_device_status
```

**请求体：**

```json
{
  "device_uuid": "dev-1",
  "new_status": 1
}
```

**返回示例：**

```json
{
  "result": "ok"
}
```

---

## 🌐 Endpoint（数据终端）相关接口

### 8. 获取所有 Endpoint

**接口：**

```
GET /get_all_endpoints
```

**参数：** 无

**返回示例：**

```json
{
  "result": [
    {
      "id": 1,
      "matcher": "/device/+",
      "title": "MQTT 接入节点",
      "type": "mqtt",
      "status": 1,
      "creator": 1,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-05-01T12:00:00Z",
      "config": {
        "host": "mqtt.broker.local",
        "port": 1883,
        "client_id": "iot-client-1",
        "username": "iot_user",
        "password": "123456",
        "topic": "iot/device/data",
        "qos": 1
      }
    },
    {
      "id": 2,
      "matcher": "/device/*",
      "title": "HTTP 推送接口",
      "type": "http",
      "status": 1,
      "creator": 2,
      "created_at": "2024-02-15T10:00:00Z",
      "updated_at": "2024-04-01T09:30:00Z",
      "config": {
        "url": "https://webhook.example.com/data",
        "pool_size": 10
      }
    },
    {
      "id": 3,
      "matcher": "/device/*",
      "title": "Kafka 接入（认证）",
      "type": "kafka",
      "status": 1,
      "creator": 3,
      "created_at": "2024-03-10T08:00:00Z",
      "updated_at": "2024-06-20T09:00:00Z",
      "config": {
        "bootstrap_servers": [
          "kafka1:9092",
          "kafka2:9092"
        ],
        "topic": "iot_topic",
        "sasl_config": {
          "username": "user_a",
          "password": "p@ssw0rd",
          "mechanism": "sha_256"
        }
      }
    },
    {
      "id": 4,
      "matcher": "/device/*",
      "title": "Kafka 接入（无认证）",
      "type": "kafka",
      "status": 1,
      "creator": 3,
      "created_at": "2024-03-15T09:30:00Z",
      "updated_at": "2024-06-25T10:15:00Z",
      "config": {
        "bootstrap_servers": [
          "kafka1:9092"
        ],
        "topic": "iot_noauth_topic"
      }
    }
  ]
}

```

---

### 9. 获取指定 Endpoint 信息

**接口：**

```
GET /get_endpoint?id=<id>
```

**参数：**

| 参数名 | 类型      | 必填 | 说明          |
| --- | ------- | -- | ----------- |
| id  | integer | ✅  | Endpoint ID |

**返回示例：()**

```json
{
  "result": {
    "id": 1,
    "matcher": "/device/+",
    "title": "MQTT接口",
    "type": "mqtt",
    "config": {
      "url": "https://webhook.example.com/data",
      "pool_size": 10
    }
  }
}
```

## 🧱 Endpoint 配置结构说明

根据 `type` 不同，`config_json` 结构如下：

### MQTT

```json
{
  "host": "broker.example.com",
  "port": 1883,
  "client_id": "client-1",
  "username": "user",
  "password": "pass",
  "topic": "iot/topic",
  "qos": 1
}
```

### HTTP

```json
{
  "url": "https://api.example.com",
  "pool_size": 5
}
```

### Kafka（带认证）

```json
{
  "bootstrap_servers": ["kafka1:9092", "kafka2:9092"],
  "topic": "iot_topic",
  "sasl_config": {
    "username": "user",
    "password": "pass",
    "mechanism": "sha_512"
  }
}
```

### Kafka（无认证）

```json
{
  "bootstrap_servers": ["kafka1:9092"],
  "topic": "iot_topic"
}
```

---

## ⚠️ 错误响应格式

统一错误返回结构：

```json
{
  "error": {
    "code": 400,
    "message": "Invalid parameter"
  }
}
```