API 概览

KolleK 的 API 是一套与网页应用一一对应的 JSON API。应用的每一项能力（创建收藏、添加藏品和副本、记录交易、管理成员）都有对应的接口，并且遵循完全相同的规则。如果你的角色允许你在浏览器里做某件事，你的令牌就能通过 HTTP 完成同样的操作；如果不允许，API 也会像应用一样拒绝。

本页帮助你建立整体认识。完整且始终最新的接口参考文档由代码自动生成，并由你的实例提供：

• /docs/api，可浏览的参考文档。
• /docs/api.md，整份参考文档的 Markdown 版本。
• /docs/api/{section}.md，单个分区的 Markdown 版本，便于把某个主题单独提供给工具使用。

限定在你的账户范围内

API 是按租户隔离的。令牌属于某个用户，而用户只属于一个账户，因此每个请求都会在该账户范围内解析。你无法访问其他账户的数据，也不需要在任何地方传递账户标识。这里没有需要配置的东西：完成身份验证后，你就已经身处自己的工作空间中。

应用中的角色规则同样适用于此。查看者的令牌只能读取，不能写入。编辑者的令牌可以管理目录内容。仅所有者可执行的操作（成员管理、账户设置）需要所有者的令牌。

资源结构

资源的嵌套方式与KolleK 的组织方式一致：

• 你的账户容纳账户级资源：成员、收藏类型、自定义字段、标签、位置、品相。
• 收藏容纳藏品，以及分类和套装。
• 藏品容纳照片和副本。
• 副本携带各类历史记录资源：交易、估值、保险记录、借还记录、保养记录、来源事件、位置历史、文档，以及合并后的时间线。

响应大致遵循 JSON:API 的结构：每个资源都以 type、id、attributes 和 links 的形式返回。列表通过统一的信封结构分页，详见 速率限制与约定。

本节涵盖的内容

本节页面涵盖入门指引，以及自动生成的参考文档无法教授的概念：身份验证、约定规范，以及 Webhook 的现状。若需查阅具体某个接口、其参数以及完整的请求与响应示例，请直接前往 /docs/api。

接下来去哪里

• 在 使用 API 进行身份验证 中发出你的第一个请求。
• 编写客户端之前，先浏览一遍 速率限制与约定。
• 在你的实例上浏览 /docs/api 处的自动生成参考文档。