开放 API

卫民CMS 提供一组只读 JSON 接口,让小程序、企业微信门户、聚合站与 AI 抓取管道能直接消费后台管理的内容。接口按站点隔离,只输出白名单字段,未发布与已删除内容不会出现在响应里。

两种访问方式

方式地址前缀认证分页上限
公开只读/api/v1/open/…免令牌,可直接体验每页 ≤ 10 条
令牌访问/api/v1/…请求头 Authorization: Bearer <令牌>每页 ≤ 50 条,计调用日志

令牌由后台「开放 API」模块创建,只保存摘要、明文仅创建时显示一次,可随时停用或重置。

接口清单(v1,全部只读)

端点说明
GET /api/v1/site站点名称、域名、TDK 等对外品牌信息
GET /api/v1/articles新闻分页,支持 page / limit / category
GET /api/v1/articles/{名称}新闻详情(含正文)
GET /api/v1/products产品分页
GET /api/v1/products/{名称}产品详情(含图集与公开报价)
GET /api/v1/pages/{名称}单页详情(关于我们、隐私政策等)
GET /api/v1/categories?type=news|product栏目树(两级)
GET /api/v1/menus?position=导航菜单
GET /api/v1/changelog版本变更日志(与本站更新日志页同源)

以上端点把 /v1/ 换成 /v1/open/ 即为公开版。

响应与错误

成功统一为 {"code":0,"message":"ok","data":…,"meta":{"site_id":…,"api_version":"v1"}};失败返回固定文案 JSON,HTTP 状态同步(401 令牌缺失或无效 / 403 无权访问当前站点 / 404 内容或接口不存在 / 429 触发限流 / 500 服务异常)。响应里不会出现账号、留言、配置等内部数据,也不会回显异常细节。

示例响应(本站真实数据)

{
    "code": 0,
    "message": "ok",
    "data": {
        "items": [
            {
                "name": "v115-deadlink-canonical",
                "title": "v1.15.0:收录闭环,死链监控、一键 301 与 URL 规范化"
            }
        ],
        "total": 2,
        "page": 1,
        "limit": 5
    },
    "meta": {
        "site_id": 1,
        "api_version": "v1"
    }
}

可直接验证:/api/v1/open/site | /api/v1/open/articles(公开版,免令牌)。

边界与规划

  • 已具备:只读内容接口、公开版体验、令牌管理与调用统计、按站点隔离与字段白名单、网关限流。
  • 规划中:写接口(内容提交)、Webhook 通知、多版本(v2)路由 —— 文档先行,交付前不冒充已上线。
  • 限流:网关层 30 次/分钟(burst 10);令牌另有每分钟调用上限的应用层兜底,后台可按令牌调整。