Headless API 指南
ReactPress 默认提供 Headless REST API，任意前端（Next.js、Remix、移动端）均可通过 HTTP 获取与写入内容。
探索 API
本地启动后访问 Swagger UI：
http://localhost:3002/api
生产环境：https://your-api-domain.com/api
认证方式
Session / JWT（Admin 同源）
Admin SPA 使用登录后的 Bearer Token，适用于浏览器内请求。
API Key（Headless 推荐）
- Admin → 设置 → API → 创建 Key
- 请求头携带：
curl -H "X-API-Key: YOUR_KEY" \
"http://localhost:3002/api/article/headless/list?status=publish&page=1&pageSize=10"
注意
API Key 等同于管理员权限，勿提交到公开仓库。生产环境使用 HTTPS 并定期轮换。
常用端点
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/health | 健康检查 |
| GET | /api/article/headless/list | 已发布文章分页列表 |
| GET | /api/article/:id | 单篇文章 |
| GET | /api/page/list | 页面列表 |
| GET | /api/category/list | 分类 |
| GET | /api/tag/list | 标签 |
| GET | /api/comment/list | 评论 |
| GET | /api/setting/public | 公开站点设置 |
| POST | /api/article | 创建文章（需鉴权） |
精确路径与参数以 Swagger 为准。
curl 示例
健康检查
curl http://localhost:3002/api/health
文章列表
curl -G "http://localhost:3002/api/article/headless/list" \
-H "X-API-Key: YOUR_KEY" \
--data-urlencode "status=publish" \
--data-urlencode "page=1" \
--data-urlencode "pageSize=10"
Toolkit SDK（TypeScript）
推荐在 Node / React 中使用强类型客户端：
npm install @fecommunity/reactpress-toolkit
import { api } from '@fecommunity/reactpress-toolkit';
const articles = await api.article.findAll({
status: 'publish',
page: 1,
pageSize: 10,
});
详见 Toolkit 使用指南。
Webhook（出站）
Server 在内容变更时向配置的 URL 发送 HTTP POST，例如 article.published。与 Plugin Hook（入站、可改数据）互补。
配置：Admin → 设置 → Webhook
自定义前端路径
- Fork reactpress-theme-starter
- 设置环境变量指向 API：
NEXT_PUBLIC_API_URL - 部署到 Vercel / 自托管 Node
- 内容仍在 ReactPress API，前端独立发布
CORS
远程 Admin / 桌面客户端 / 第三方前端需 API 允许对应 Origin。生产部署时在 Server 或 Nginx 层配置 CORS 白名单。