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错误,不同接口可能有不同的限流策略。
建议 — 合理控制调用频率,批量操作使用批量接口,做好错误重试机制(带退避),缓存不需要实时更新的数据。
安全最佳实践
- 使用HTTPS:确保API调用通过HTTPS传输
- 保护Token:不要在客户端代码中暴露Token
- 最小权限:按实际需要分配接口权限
- 定期轮换:定期更换API Token
- IP白名单:企业版支持设置IP白名单
- 监控日志:定期检查API调用日志