跳转到内容
BangNiCMS 文档

API 总览

BangNiCMS 提供完整的 REST API——所有后台能做的事 API 都能做。

API 入口

Section titled “API 入口”
基础 URL：https://yourdomain.com/api

认证

Section titled “认证”

方式 A：用户 Token（推荐）

Section titled “方式 A：用户 Token（推荐）”

用户登录后获得 token，请求时携带：

Authorization: Bearer <token>

适合：

  • 后台管理操作
  • 用户身份相关的操作

方式 B：API Key（机器调用）

Section titled “方式 B：API Key（机器调用）”

适合自动化脚本 / 第三方集成：

  • 在「用户管理 → API Key」创建
  • 请求时携带：
X-API-Key: <api-key>

安全建议：

  • API Key 严格保密（不放代码、不发群）
  • 限制 IP 范围
  • 限制权限范围（只读 / 写）
  • 定期轮换（每 6-12 月）

模块概览

Section titled “模块概览”
模块路径用途
内容/api/products /api/articles /api/pages /api/downloadsCRUD 内容
分类 / 菜单/api/categories /api/menus组织结构
媒体/api/media /api/media/upload图片 / 文件
多语言/api/languages /api/i18n语言 / 翻译
站点设置/api/site-config站点配置
询盘/api/inquiries询盘
用户/api/users用户管理
扩展/api/extensions主题 / 插件
AI/api/ai/translate /api/ai/visionAI 调用

具体接口看在线 OpenAPI / Swagger 文档（开发环境通常是 /api/docs）。

通用规范

Section titled “通用规范”

请求

Section titled “请求”
  • Content-Type：application/json（除文件上传 multipart/form-data）
  • 方法：GET / POST / PUT / DELETE 标准 REST
  • 分页：?page=1&pageSize=20
  • 筛选：?status=published&category=industrial
  • 排序：?sort=-createdAt（- 表示降序）

响应

Section titled “响应”

成功：

{
  "data": { ... },
  "meta": { "total": 100, "page": 1 }
}

失败：

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Product not found",
    "details": { ... }
  }
}

状态码

Section titled “状态码”
码含义
200成功
201创建成功
204删除成功（无内容返回）
400请求参数错
401未认证
403无权限
404资源不存在
409冲突（如重名）
429限流
500服务器错

多语言

Section titled “多语言”

请求时通过 query 或 header 指定语言：

GET /api/products/abc?lang=en

或

Accept-Language: en

返回的内容字段为对应语言版本。

文件上传

Section titled “文件上传”
POST /api/media/upload
Content-Type: multipart/form-data


file: <binary>
folder: products
alt: 产品封面

返回：

{
  "id": "media_123",
  "url": "https://cdn.../products/abc.jpg",
  "size": 102400,
  ...
}

详见 上传与媒体设置 的策略。

Webhook

Section titled “Webhook”

BangNiCMS 支持向你的系统主动推送事件：

事件触发时机
inquiry.created新询盘提交
inquiry.updated询盘状态变化
content.published内容发布
content.deleted内容删除
user.login用户登录

配置：「站点设置 → Webhook」添加目标 URL。

接收：你的服务接收 POST 请求处理事件。

限流

Section titled “限流”

默认限流：

  • 普通用户：100 次 / 分钟
  • 高权限：500 次 / 分钟
  • API Key：可配（默认 1000 次 / 分钟）

超出 → 429 错误。

版本

Section titled “版本”
  • 当前版本：v1（路径前缀 /api）
  • 未来可能 /api/v2

向后兼容：我们承诺 v1 至少维护 2 年。

开发者工具

Section titled “开发者工具”
  • Swagger UI：/api/docs（开发环境）
  • Postman Collection：官方导出
  • TypeScript SDK：@bangnicms/sdk（npm 包）
  • CLI：bangnicms-cli（命令行调用）

调试技巧

Section titled “调试技巧”
工具用
Postman / Insomnia手动测试
curl命令行测试
Chrome DevTools看浏览器请求
API 日志让运维查看

安全建议

Section titled “安全建议”
  • 永远用 HTTPS
  • API Key 不放前端代码
  • 用户 token 放安全 cookie（HttpOnly / Secure）
  • 输入校验
  • SQL 注入防护（用 ORM 自动防）
  • XSS 防护（输出转义）

接下来

Section titled “接下来”