# API 参考

公开消费使用 S3/CDN binding，管理操作使用 `/v1/graphql` 和 scoped PAT。
Dashboard 工作区使用服务端 session，worker 使用独立内部接口。

- [认证](./authentication.md)
- [完整 GraphQL operations](./reference.md)
- [错误与恢复](./errors.md)
- [静态分发 schema](/schemas/distribution-v1.schema.json)
- <a href="/assets/55b4e1c7b91f8f7fa711eac60cff25051b2b68a70fe0429e4af218e815c9afb2/docs/api/schema.graphql">GraphQL SDL</a>
- [Marketplace manifest schema](/schemas/plugin.schema.json)
- [Manifest projection schema](/schemas/core.schema.json)
- [Source-release schema](/schemas/source-release-v1.schema.json)

## 公开读取

```text
GET revision/stable_latest
GET revision/<revision_id>
```

Pointer 内容恰为64个小写hex字符，没有JSON或换行；revision是snapshot原始JSON字节的
SHA-256。Snapshot引用catalog、package lookup及其immutable文档，descriptor提供path/hash/size。
客户端校验authority、channel、schema和摘要，一次操作固定一个snapshot，不回退GraphQL。

`revision/preview_latest`包含所有批准stable/prerelease；stable不含prerelease。
Pointer最多缓存五分钟，并计入HTTP Age；immutable对象可长期缓存。显式历史revision不代表当前政策。
包名为准确canonical namespace/name，不转换大小写或下划线。公开UUID不授予管理权限。

## 发布与可见性

Plugin 是身份、所有权与生命周期；listing 是关联的市场展示。草稿和pending数据不进入公开snapshot。
隐藏的正式包从discovery移除，准确lookup保留且listing为null，历史公开文档仍可读。
创建草稿后通过 submit_release 一次提交初次 listing 快照及版本，管理员一次审核。
最终鉴权并durable提交publication commitment后才写公开bucket。所需channel与HTML确认后才为published。
临时材料保留7天；公开制品包含相对公开path、摘要、大小和manifest，不含private object key或grant。

## 发布查询与恢复

`publication_status`按原actor/command查询，检查当前owner/admin和plugins:read；只有管理员可查其他actor。
结果区分每个channel的revision、covering revision和web状态。`recover_publication`要求当前管理员、
admin:write和expected_revision，保留原commitment/source identity，重新排队有界核对。
恢复请求自身applied只证明已排队，原publication全部channel/web完成才证明公开完成。