@ cloudhal/ api (英语)
Cloudhal HTTP API作为Hono应用程序——一个 fetch 在节点上运行的处理器( E)@cloudhal/api/node和在云花岗工人.
核心路由如下;特色路由(分类,菜单,介质,评论,时间表,分析,成员,批准,.)是各入一单元 src/routes/。 。 。 .
| 路线 | 什麽 |
|---|---|
GET /api/health | 活 动 |
GET /api/me | 呼叫演员( 匿名时401) |
/api/auth/* | 更好的Auth( 签名、 登录、 会话、 组织、 管理员) |
GET/PUT /api/sites[/:id] | 站点 (PUT = 完整文档, CAS 上) rev(中文(简体) ) |
GET /api/sites/:id/pending | 出版会携带什么(Studio的徽章 |
/api/sites/:id/pages[/:pageId] | 页面( POST 创建和附加到 Site.pageIds 解剖学; DELETE 需要 ?rev=(中文(简体) ) |
/api/sites/:id/entries[/:entryId] | 内容条目( e)?collection=, (中文(简体) ), locale, (中文(简体) ), status, (中文(简体) ), filter(三); fields 对照收藏的打出字段(RFC-0041)检查,以及 null 删除此处的密钥。 RFC-0042 第4节:与 collection, (中文(简体) ), where (JSON名单最多4人) {field, op, value?/values?}按类型分列的行动, value: "now" 日期/时间)和 orderBy (杰森语) {field, direction: "asc"|"desc"}过滤并排序于收藏的 listFields,比如说. ?collection=events&where=[{"field":"startsAt","op":"gte","value":"now"}]&orderBy={"field":"startsAt","direction":"asc"} (URL编码). limit (1-100)页,答复如下: {entries, total, nextCursor?},继续 cursor=<nextCursor>; 无 limit 答案保留平原数组 |
/api/sites/:id/collections[/:key] | 收集登记册; PUT /:key {settings, rev} (单位:千美元)?dryRun=1) 宣布收藏或更改其设置,键入 fields 包括; DELETE /:key?rev= |
/api/sites/:id/collections/:key/fields/operations | RFC-0041 第6节 外地行动(site:settings 财务报告和审定财务报表 content:write: POST {op, …, dryRun?} 与 op 一个 rename_field {from, to}, (中文(简体) ), change_field_type {key, type, options?, multiple?, onInvalid?: "clear"}, (中文(简体) ), set_field_localized {key, localized}, (中文(简体) ), remove_field {key} → {operationId, done, report, rewritten, skipped} (干燥笔迹; done: false 当2000入/20的预算用完时 POST ?continue=<operationId>(三); GET /:operationId - 说明和待处理条目; POST /:operationId/revert (又时 done: false) (中文(简体) ). 只有图表草稿更改 |
/api/sites/:id/snapshots | 创建( n){label, publish}),名单, :id/publish, (中文(简体) ), :id/rollback, (中文(简体) ), :a/diff/:b |
/api/agent-keys | 代理的 API 密钥 : POST {name, scopes} (键显示一次), GET, (中文(简体) ), DELETE /:id ——只签入人类 |
/mcp | cloudhal MCP服务器(ADR-0011); 会话 cookie → 人, x-api-key 或者说 Authorization: Bearer <key> + 限于密钥瞄准镜的代理键( REST 回答密钥并带有指针) /mcp(中文(简体) ) |
错误 : 400 validation (合同错误和详细情况), 409 conflict (单位:千美元)expectedRev编号 :actualRev, (中文(简体) ), 409 unique, (中文(简体) ), 404 not_found, (中文(简体) ), 401 unauthorized. 储存不变量用其代码回答(src/errors.ts, (中文(简体) ), INVARIANT_STATUS) (中文(简体) ).
输入字段( RFC- 0041) 回答每个问题及其路径 details.issues (单位:千美元)[{ path: "fields/startsAt/at", code, message }]:
| 代码 | 状态 | 何时 |
|---|---|---|
invalid_fields | 422个 | 不符合其定义的数值(或同时出现几种问题) |
unknown_field | 422个 | 一个没有定义的新密钥, 在有定义的集合中 |
field_not_localized | 422个 | a 翻译本身的非本地化值副本(设置在正本上) |
required_field | 422个 | 已审查的条目或未经审查而公布的条目 requiredToPublish 价值 |
too_large | 409个 | fields 超过 256 KB, 或 超过 256 KB 的收藏设置 |
field_key_reserved, (中文(简体) ), field_key_duplicate, (中文(简体) ), field_option_duplicate, (中文(简体) ), field_bounds | 400个 | 永远无法保存为书面的定义 |
too_many_fields | 422个 | 每件收集超过30个字段,每个站点200个或每个选择的50个选项 |
field_change_needs_operation | 409个 | 更改字段类型、本地化或 multiple键或选项 |
operation_in_progress | 409个 | 另一个外地行动仍在重写收藏(details.operationId(中文(简体) ) |
field_values_unconvertible | 422个 | 类型变化会丢弃转换表无法转换的值, 不 onInvalid: "clear" (单位:千美元)details.report 是干线) |
field_operation_incomplete | 409个 | 返回未完成或已恢复的操作 |
收集阶段3(RFC-0042)答案相同(details.issues,斜线路径 :
| 代码 | 状态 | 何时 |
|---|---|---|
invalid_query | 422个 | 条目列表 where编号 :orderBy编号 :limit编号 :cursor,或一个 contentList 节'(sections/2/where/0/value),命名一个未列出的字段,一个运算符或其类型不取值,或打破约束 |
unknown_field | 422个 | listFields 或者说 expiry.field 名称没有收藏字段 |
invalid_expiry | 422个 | expiry.field 不是一个日期或日期字段 |
structured_data_invalid | 422个 | (单位:千美元) structuredData 预设与类型表或收藏字段不符(不拒绝警告) |
list_field_in_use | 409个 | 取消列表字段( 或删除选择的选项) , 或删除该字段 contentList 区域仍在使用(details.pages(三); remove_field 指定字段 listFields, (中文(简体) ), expiry 或者说 structuredData; 类型变化会打破这些段落. rename_field 重命名这些引用 |
import { createApi } from "@cloudhal/api";
import { createAuth } from "@cloudhal/api/auth";
const auth = createAuth({ database: db, baseURL, secret });
const app = createApi({
store,
resolveActor: auth.resolveActor,
resolvePrincipal: auth.resolvePrincipal,
authHandler: auth.handler,
agentKeys: auth.agentKeys,
mcp: { stateKey: process.env.MCP_STATE_KEY, audit, skills },
});
Auth (ADR- 0010): 更好的Auth 1.7 与电子邮件+密码字, organization 财务报告和审定财务报表 admin; 会话决定 Actor { kind: "human", id: "user_…" }. Auth 表格存在于存储迁移中 0002_auth共享测试套件(src/testing.ts) 运行在更佳的sqlite3和miniflare D1上,包括文章工作流程草案-审查-已出版-快照-已出版-已出版-回滚.