参考 HTTP 路由
HTTP 路由
位于处理器的
base 之下，本文档中为 /api/files。构建本网站时从 packages/server/src/api.ts 开头的注释中读取，因此包含代码中的全部路由；每条路由的作用在此译出。请求和响应体均为 JSON；拒绝时返回 { error, message } 及相应状态码：message 为英文，云盘会根据 error 用每个人的语言显示。已登录用户
每条路由都会询问 identify 是谁在请求，并询问 authorize 是否允许。
| 路由 | 作用 |
|---|---|
GET/entries?folder=… | 文件夹中的内容（不指定：最顶层），以及它所在的位置 |
GET/entries/:id | 单个条目，以及它所在的位置 |
GET/recent | 最近更改的文件 |
GET/trash | 回收站中的内容 |
GET/starred | 请求者加星标的内容，最近加星标的排在前面 |
PUT/entries/:id/star | 加星标，仅对请求者 |
DELETE/entries/:id/star | 取消星标 |
GET/search?q=…&within=…&trashed=1 | 按名称查找 |
POST/folders | { name, parent } |
POST/uploads | { name, parent, type, size }，或新版本用 { file, type, size }：各部分发往何处；或 { rendition: { file, version, size, width, height }, type, size }：某个版本的缩略图 |
POST/uploads/finish | { token, parts: [{ number, etag }] }：字节到达后，生成文件 |
POST/uploads/resume | { token }：继续中断的上传：已到达的部分，以及其余部分发往何处 |
POST/uploads/abort | { token }：放弃上传，并删除已到达的部分 |
PATCH/entries/:id | { name }、{ parent }、{ color } 或 { fields }，加 { ifTaken: 'keep-both' } 时追加 "(2)" |
GET/fields?name=…&value=… | 字段为该值且可读取的内容 |
POST/entries/:id/copy | { parent }：复制文件，内容在存储中复制；默认放在原文件旁边，或放在自己的顶层 |
POST/entries/:id/trash | 移入回收站 |
POST/entries/:id/restore | 移出回收站 |
DELETE/entries/:id | 从回收站中永久删除 |
POST/trash/empty | 清空请求者的回收站 |
GET/entries/:id/download?version=&inline=1&size= | 用于读取或在页面中显示的地址；带 size 时，返回已有的较小图片 |
POST/entries/:id/versions/:v/restore | 将较早的版本恢复为当前版本 |
POST/zip | { ids }：它们的 .zip 包含的内容，文件夹连同其内容，按路径排列 |
POST/urls | { ids, inline, size }：一次获取多个文件的地址，用于网格；以及每个地址的有效期 |
GET/info | 字节存放在哪里，以人可读的方式 |
GET/usage | 请求者占用的字节数，以及上限 |
GET/settings | 云盘的设置、请求者自己的设置，以及能否更改云盘设置 |
GET/people?q= | 与输入匹配的人，用于共享（需 `people`） |
POST/people/names | { ids }：每个人的名称（需 `people.names`） |
PUT/settings | 云盘的设置，供有 'configure' 权限的人使用 |
PUT/settings/mine | { language, theme }：自己的设置 |
GET/entries/:id/activity?limit= | 对它所做的操作，若是文件夹，还包括其中的内容，最新的在前 |
GET/search/text?q= | 按文件中的文字查找，并附上找到处周围的一段 |
PUT/entries/:id/text | { version, text }：页面读取的文件文字，用于搜索 |
PUT/entries/:id/placeholder | { version, placeholder }：图片加载前模糊显示的小图 |
POST/duplicates | { hashes }：在可读范围内，已有相同字节的文件 |
GET/shared | 他人与请求者共享的内容 |
GET/shared/new | 自上次查看以来新增的数量 |
POST/shared/seen | 已查看：不再有新的 |
POST/entries/:id/shares | { with, role, days }：共享或更改角色；共享指定天数，null 为永久，不指定则保持原样 |
DELETE/entries/:id/shares/:with | 不再与其共享 |
POST/entries/:id/links | { days, password, once }：无需登录即可读取的链接及其地址 |
GET/entries/:id/links/:link | 再次获取链接的地址 |
DELETE/entries/:id/links/:link | 撤回链接 |
GET/entries/:id/comments | what is said of it, each thread with its replies under it |
POST/entries/:id/comments | { text, replyTo }: a comment, or a reply; those it names with @ told (onComment) |
PATCH/entries/:id/comments/:c | { text } by its author, or { resolved: true | false } |
DELETE/entries/:id/comments/:c | by its author, or by who may share the entry |
PUT/entries/:id/hold | { reason }: on hold, for who may 'configure': not to be trashed or deleted |
DELETE/entries/:id/hold | released |
GET/notifications | 请求者收到的通知（与其或其所在组共享、在评论中被提到），最新的在前，以及新通知数量 |
POST/notifications/seen | 已查看：不再有新通知 |
GET/admin/usage | 供有配置权限的人使用：每个人保存的内容（文件、文件夹、字节）和整个网盘 |
GET/admin/activity?limit= | 供有配置权限的人使用：网盘中任何位置的操作，最新的在前 |
GET/export?user=… | everything of a person (oneself, or anyone for who may 'configure'), for a .zip |
GET/events | 实时的更改（server-sent events）：每次更改中自己可见的文件夹和条目 |
通过链接
两者都不询问：链接本身就是权限。带密码的链接会在每次请求时要求提供密码。
| 路由 | 作用 |
|---|---|
GET/links/:token?folder=… | 链接可读取的内容，或其中的某个文件夹 |
GET/links/:token/download?id=…&inline=1 | 读取链接中某个文件的地址 |
GET/links/:token/zip?ids=… | 其中部分内容（未指定则全部）的 .zip 包含的内容 |
GET/links/:token/urls?ids=… | 其中部分文件的地址 |
POST/links/:token/uploads | { name, folder, type, size }，以及 /finish、/abort：通过可接收文件的链接（{ uploads }）上传文件 |
DELETE/links/:token/sent/:receipt | 十分钟内凭上传给出的回执，撤回刚通过链接发送的文件 |
PATCH/entries/:id/links/:link | { days, uploads, request, closed }：修改链接，关闭或重新打开 |
PUT/entries/:id/review | { status: 'accepted' | 'rejected' | null, reason }：审阅通过文件收集收到的文件 |
GET/received | 通过提问者的文件收集收到的内容，最新的在前 |
GET/requests | 提问者的文件收集：每个文件夹、其链接、令牌和已收到的内容 |
GET/admin/requests | 供有配置权限的人使用：每个文件收集、发送给了谁以及还缺什么 |
POST/entries/:id/links/:link/remind | 立即提醒请求的收件人还缺什么（需配置 `reminders`） |
GET/expiring?days= | 自己可读、字段 expires 表明在若干天内失效的文件 |