API接口概览

智站CMS提供完整的RESTful API接口,方便开发者进行二次开发和系统集成。

接口特点

  • RESTful设计:遵循REST规范,语义清晰
  • JSON格式:请求和响应都是JSON格式
  • Token鉴权:Bearer Token认证方式
  • 版本管理:API地址包含版本号,如/api/v1/
  • 限流保护:防止接口滥用
  • 详细日志:记录所有API调用

基础信息

API地址 — https://你的域名/api/v1/

数据格式 — 所有请求和响应都使用JSON格式,Content-Type为application/json。

鉴权方式 — 使用Bearer Token认证,在请求头中携带:Authorization: Bearer

获取Token:在后台「系统设置」→「API令牌管理」中创建。

响应格式

成功响应 — 包含code(0表示成功)、message(success)、data(返回数据,列表接口包含items、total、page、limit)。

错误响应 — 包含code(非0错误码)、message(错误信息)、data(null)。

接口列表

文章相关

  • GET /api/v1/articles — 获取文章列表
  • GET /api/v1/articles/{id} — 获取文章详情
  • POST /api/v1/articles — 创建文章
  • PUT /api/v1/articles/{id} — 更新文章
  • DELETE /api/v1/articles/{id} — 删除文章

产品相关

  • GET /api/v1/products — 获取产品列表
  • GET /api/v1/products/{id} — 获取产品详情
  • POST /api/v1/products — 创建产品
  • PUT /api/v1/products/{id} — 更新产品
  • DELETE /api/v1/products/{id} — 删除产品

分类相关

  • GET /api/v1/categories — 获取分类列表
  • POST /api/v1/categories — 创建分类
  • PUT /api/v1/categories/{id} — 更新分类
  • DELETE /api/v1/categories/{id} — 删除分类

站点相关

  • GET /api/v1/sites — 获取站点列表
  • GET /api/v1/sites/{id} — 获取站点详情

完整接口文档请在后台「API文档」页面查看(企业版)。

公共参数

分页参数 — page(页码默认1)、limit(每页数量默认20最大100)。

筛选参数 — site_id(站点ID多站点模式下必需)、category_id(分类ID)、status(状态筛选)、keyword(关键词搜索)。

排序参数 — order_by(排序字段如id、created_at、views)、order(排序方向asc/desc)。

状态码

HTTP状态码 — 200成功、400请求参数错误、401未认证、403无权限、404资源不存在、429请求过于频繁、500服务器内部错误。

业务错误码 — 0成功、40001参数错误、40101Token缺失、40102Token无效、40103Token已过期、40301无接口权限、40302无站点权限、40401资源不存在。

限流说明

限制规则 — 每个Token每分钟最多60次请求,超出限制返回429错误,不同接口可能有不同的限流策略。

建议 — 合理控制调用频率,批量操作使用批量接口,做好错误重试机制(带退避),缓存不需要实时更新的数据。

安全最佳实践

  1. 使用HTTPS:确保API调用通过HTTPS传输
  2. 保护Token:不要在客户端代码中暴露Token
  3. 最小权限:按实际需要分配接口权限
  4. 定期轮换:定期更换API Token
  5. IP白名单:企业版支持设置IP白名单
  6. 监控日志:定期检查API调用日志