API令牌管理
智站CMS提供完整的RESTful API接口,支持通过API管理站点、文章、产品等内容。API令牌用于接口鉴权,确保安全访问。
API总览
接口特点
- RESTful风格设计
- JSON数据格式
- Token鉴权
- 细粒度权限控制
- 站点级数据隔离
- 调用日志记录
适用场景 — 自定义前端开发、第三方系统集成、移动端App开发、自动化脚本、数据同步。
令牌管理
创建令牌
- 进入「系统设置」→「API令牌管理」
- 点击「新建令牌」
- 填写令牌名称(方便识别)
- 设置权限范围:文章读取/写入、产品读取/写入、分类读取/写入等
- 选择授权站点(可绑定特定站点)
- 设置过期时间(可选)
- 点击「创建」
创建后会显示Token,请妥善保存,只显示一次。
令牌权限
系统级开关 — API总开关:关闭后所有API都不可用;单个接口开关:可以单独开启/关闭某个接口。
令牌级权限 — 读取权限(GET接口)、写入权限(POST/PUT/DELETE接口)、按模块授权(文章、产品、分类、站点等)。
站点级权限 — 全部站点:令牌可以访问所有站点的数据;指定站点:只能访问授权的站点数据。
建议遵循最小权限原则,只给需要的权限。
令牌状态
- 正常:令牌可以正常使用
- 已禁用:令牌暂时失效
- 已过期:超过设置的过期时间
- 已删除:令牌已被删除
操作令牌 — 禁用/启用(临时禁用或重新启用令牌)、编辑(修改令牌名称、权限、授权站点等)、删除(永久删除令牌不可恢复)、查看日志(查看该令牌的调用记录)。
接口调用
鉴权方式 — 使用Bearer Token鉴权,在请求头中携带:Authorization: Bearer {your-token}
基础URL — https://你的域名/api/v1/
响应格式 — 所有接口返回JSON格式,包含code(0表示成功非0表示错误)、message(提示信息)、data(返回数据)。
文章接口
获取文章列表 — GET /api/v1/articles,参数包括site_id(站点ID必需)、category_id(分类ID可选)、page(页码默认1)、limit(每页数量默认20)、status(状态筛选)。
获取单篇文章 — GET /api/v1/articles/{id}
创建文章 — POST /api/v1/articles,请求体包含site_id、title、content、category_id、status等字段。
更新文章 — PUT /api/v1/articles/{id}
删除文章 — DELETE /api/v1/articles/{id}
产品接口
和文章接口类似:获取产品列表、获取产品详情、创建产品、更新产品、删除产品。
分类接口
获取分类列表、创建分类、更新分类、删除分类。
错误码说明
| 错误码 | 说明 |
|---|---|
| 0 | 成功 |
| 401 | 未授权(Token无效或过期) |
| 403 | 无权限(Token没有该接口权限) |
| 404 | 资源不存在 |
| 429 | 请求过于频繁 |
| 500 | 服务器内部错误 |
限流策略
为了防止滥用,API接口有频率限制:每个Token每分钟最多60次请求,超出限制会返回429错误,企业版可以调整限流阈值。
安全建议
- 妥善保管Token:不要把Token提交到公开代码库
- 最小权限:只给需要的权限
- 定期轮换:定期更换Token
- 使用HTTPS:确保传输安全
- 监控日志:定期检查API调用日志,发现异常及时处理