---

```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 |

**返回示例：**

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

---

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

**接口：**

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

**参数：**

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

**返回示例：**

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

---

### 4. 修改主机状态

**接口：**

```
POST /change_host_status
```

**请求体：**

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

**返回示例：**

```json
{
  "result": 1
}
```

---

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

**接口：**

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

**参数：**

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

**返回示例：**

```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 |

**返回示例：**

```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": 1
}
```

---

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

### 8. 获取所有 Endpoint

**接口：**

```
GET /get_all_endpoints
```

**参数：** 无

**返回示例：**

```json
{
  "result": [
    {
      "id": 1,
      "name": "mqtt_endpoint",
      "type": "mqtt",
      "status": 1
    }
  ]
}
```

---

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

**接口：**

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

**参数：**

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

**返回示例：**

```json
{
  "result": {
    "id": 1,
    "name": "mqtt_endpoint",
    "title": "MQTT接口",
    "type": "mqtt",
    "config_json": "{\"host\":\"mqtt.example.com\",\"port\":1883}"
  }
}
```

---

## 🤖 AI 事件接口

### 10. 触发 AI 事件

**接口：**

```
POST {api_url}
```

**请求体：**

```json
{
  "id": 123,
  "token": "<md5(API_TOKEN + id + API_TOKEN)>"
}
```

**返回：**

* 成功：HTTP 200
* 失败：返回错误日志（`lager` 记录）

**说明：**
`token` 通过以下 Erlang 表达式生成：

```erlang
iot_util:md5(<<API_TOKEN, integer_to_binary(Id), API_TOKEN>>)
```

---

## 🧱 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"
  }
}
```

---

## 📄 附录：内部函数说明（开发者参考）

| 函数名                 | 作用                            | 说明                                    |
| ------------------- | ----------------------------- | ------------------------------------- |
| `do_get/2`          | 执行 HTTP GET 请求                | 返回 `{ok, Result}` 或 `{error, Reason}` |
| `do_post/2`         | 执行 HTTP POST 请求               | 自动编码 JSON，解析返回值                       |
| `endpoint_record/1` | 将 JSON 转换为内部 `#endpoint{}` 结构 | 内部使用                                  |
| `parse_config/2`    | 解析不同类型 endpoint 配置            | 支持 mqtt/http/kafka                    |

---

📅 **最后更新：2025-11-07**

```

---

是否希望我帮你把这份 `.md` 文件转成一个 **可浏览的 HTML 文档**（带目录与搜索功能）？
```