API 概述

通过开放 API，你可以管理设备、因子和数据，快速构建物联网应用。

基本信息

项目	值
Base URL	https://dl.yengear.com/api/v2
协议	HTTPS
格式	JSON

---

请求规范

请求头

所有请求必须包含以下 Header：

Header	必填	说明
Authorization	是	认证令牌，格式：Bearer <ACCESS_TOKEN>
X-Organization-Slug	是	组织标识符，如 my-org
Content-Type	POST/PUT	请求体格式，固定为 application/json

请求示例

curl https://dl.yengear.com/api/v2/projects/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-Slug: your-org-slug"

路径参数

API 路径中的参数使用 {param} 表示，调用时需替换为实际值：

参数	说明	示例
{project_id}	项目 ID	proj_hBonHEAQhm
{device_id}	设备主键 ID	17644
{id}	资源 ID	5855

查询参数

GET 请求的查询参数通过 URL 传递：

GET /api/v2/projects/{project_id}/devices/?page=1&page_size=20

请求体

POST/PUT 请求的数据通过 JSON 格式传递：

curl -X POST https://dl.yengear.com/api/v2/projects/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-Slug: your-org-slug" \
  -H "Content-Type: application/json" \
  -d '{"name": "新项目"}'

---

认证

所有请求需在 Header 中携带 Access Token：

Authorization: Bearer <ACCESS_TOKEN>

Token 可在设备管理平台的「组织设置」页面创建和管理，详见 Access Token。

快速开始

cURL

curl https://dl.yengear.com/api/v2/projects/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-Slug: your-org-slug"

Python

import requests

API_BASE = "https://dl.yengear.com/api/v2"
TOKEN = "YOUR_TOKEN"
ORG_SLUG = "your-org-slug"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "X-Organization-Slug": ORG_SLUG
}

response = requests.get(f"{API_BASE}/projects/", headers=headers)
print(response.json())

响应格式

成功响应

单个对象直接返回数据，列表返回数组。HTTP 状态码为 200、201 或 204。

{
    "project_id": "proj_abc123",
    "name": "我的项目",
    "device_count": 10
}

错误响应

{
    "error": {
        "code": "NOT_FOUND",
        "message": "项目不存在"
    }
}

HTTP 状态码

状态码	说明
200	请求成功
201	创建成功
204	删除成功（无响应体）
400	请求参数错误
401	未认证或 Token 无效
403	无权限
404	资源不存在
429	请求过于频繁
500	服务器错误

分页

列表接口支持分页：

参数	类型	默认值	说明
page	integer	1	页码
page_size	integer	20	每页数量

限制

• 请求频率：100 次/分钟
• 请求体大小：10 MB

相关文档

• 快速开始 - 快速上手指南
• Access Token - 如何创建和管理访问令牌