项目 API 通用约定(认证与访问)
本文是 project/ 下全部功能 API 的公共约定:认证头、scope、请求/响应格式、统一错误模型、分页与限流。各功能点的端点、参数与错误细节见对应文档(索引见文末「与 Server SDK 的对应」表)。
资源与基础路径
- Base URL:
https://<your-endpoint>/v1。下文各文档中的端点路径均为此基础路径下的相对路径,逐字来自上游 spec(版本 2.6.0)。 - 路径中的占位符(如
{userId}、{databaseId})为资源标识:既可使用自定义 ID(创建时以请求体字段指定),也可使用服务端生成的唯一 ID。 - 所有项目级资源都挂在单个项目之下:请求头指定项目后,路径与查询都作用于该项目内的资源。
认证与权限
服务端访问使用两个请求头(兼容命名):
| 请求头 | 含义 |
|---|---|
X-Appwrite-Project | 项目 ID |
X-Appwrite-Key | 项目 API Key(在该项目的设置中创建) |
约定要点:
- API Key 创建时绑定一组 scope(如
users.read、files.write)。每个端点在 spec 中标注其所需 scope;文档中各端点表同时列出。 - 部分端点标注 scope 数组(如
tables.write/collections.write):这是同一能力的新旧命名兼容别名,Key 持有其中任意一个即可通过检查。 - Key 缺失、无效或项目不匹配:返回
401,错误类型general_access_forbidden。 - Key 有效但缺少所需 scope:返回
401,错误类型general_unauthorized_scope。 - 资源存在但调用方无权访问(资源级权限,见 permissions):多数读路径返回
404(不泄露存在性),管理类路径可能返回403(general_resource_blocked等)。 - API Key 属于服务端凭证:不要下发到浏览器或客户端应用;客户端语境的登录与 Session 流不在本目录范围。
请求与响应格式
GET/DELETE的过滤参数走 URL 查询串;POST/PUT/PATCH走application/json请求体。分页参数queries统一为数组形式(queries[]=...)。- 文件上传类端点(如函数与站点的部署包上传)使用
multipart/form-data。 - 响应为 JSON。列表类响应统一为
total(匹配总数,整数)+ 资源名字段(如rows、users、files)的结构;多数列表端点接受total=false跳过计数以降低开销。 - 下载类端点(文件
download/view/preview、部署包download、知识库文档source)返回二进制流或重定向,不返回 JSON。
统一错误模型
非 2xx 响应统一为如下结构:
{
"message": "Not found",
"code": 404,
"type": "not_found",
"version": "2.6.0",
"requestId": "<关联 ID,用于排障与观测查询>"
}type为小写下划线字符串;通用错误类型包括general_access_forbidden(401)、general_unauthorized_scope(401)、general_resource_blocked(403)、general_route_not_found(404)、general_cursor_not_found(400)、general_rate_limit_exceeded(429)、general_service_unavailable(503)等。- 各功能域有自己的语义错误类型(如
user_not_found、database_not_found、storage_bucket_not_found),在对应文档的「错误与边界」一节登记。 code字段与 HTTP 状态码一致;重试判断以状态码 +type共同决定。
分页与查询
列表端点接受 queries 数组,每个元素是一条查询字符串(SDK 中由 Query 构造器生成,形如 limit(25)、cursorAfter("...")、equal("name","x")):
- 分页用
limit(n)、offset(n)或cursorBefore/cursorAfter(cursorId);cursor取自上一页最后一个资源的$id,游标不存在时返回general_cursor_not_found。 - 单次请求最多 100 条 query,每条最长 4096 字符;
limit单页上限以各端点标注为准(多数为 100)。 - 过滤仅支持端点标注的可过滤字段(各文档「请求与响应」节说明),对不支持的字段查询会被拒绝。
- 列表顺序:未指定
orderBy时按创建序返回;total=false时total恒为 0。
限流与幂等
- 限流按「账户 → 项目 → 调用方」三层令牌桶执行;响应携带
X-RateLimit-Limit/X-RateLimit-Remaining/X-RateLimit-Reset头,反映最紧的一层。 - 超限返回
429,错误类型general_rate_limit_exceeded,并携带Retry-After头。 - 各端点在 spec 中标注独立限流额度(次/秒或次/小时);未标注的端点走实例默认限流。
- 幂等语义:
GET幂等;PUT语义为创建或整体更新(create-or-replace);PATCH为局部更新;批量 upsert 端点按文档逐个说明。跨多资源的原子写入使用事务(见 databases)。
完整调用示例
以下示例演示一次典型调用的完整形态:两头认证、数组型分页 query、total=false 跳过计数。
列出用户(带分页与过滤,queries[] 为数组形式):
curl \
'https://<your-endpoint>/v1/users?queries[]=limit(25)&queries[]=offset(0)&queries[]=equal("status","true")&total=false' \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"创建资源(JSON 请求体;以团队为例):
curl -X POST "https://<your-endpoint>/v1/teams" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"teamId": "unique()",
"name": "Platform"
}'成功响应为 201 + 资源 JSON;列表响应形如 {"total": 0, "teams": []}(total=false 时 total 恒为 0)。
典型错误响应(Key 缺失或无效,401):
{
"message": "Not found",
"code": 401,
"type": "general_access_forbidden",
"version": "2.6.0"
}Key 有效但缺 scope(401):
{
"message": "The current API key does not have the required scope to perform this action.",
"code": 401,
"type": "general_unauthorized_scope",
"version": "2.6.0"
}限流超限(429,携带 Retry-After 响应头):
{
"message": "Too many requests",
"code": 429,
"type": "general_rate_limit_exceeded",
"version": "2.6.0"
}排障时同时查看三处:HTTP 状态码、错误 type、响应头 X-RateLimit-Remaining / Retry-After;requestId 可用于观测平台的请求级检索。
与 Server SDK 的对应
全部 Server SDK service 共用本页约定;HTTP 层差异只体现在端点与参数,认证头、错误模型、分页与限流语义完全一致。
| Server SDK service | API 文档 |
|---|---|
Users | users |
Teams | teams |
TablesDB / DocumentsDB / Databases | databases |
Storage | storage |
Tokens | file-tokens |
Functions | functions |
Project | projects |
Messaging | messaging |
Sites | sites |
Memory | memory |
KnowledgeBases | knowledge-bases |
LlmGateway | llm-gateway |
AiGateway | ai-gateway |
Observability | observability |
Moderation | moderation |
Webhooks / Graphql / Avatars / Locale / Health | misc/webhooks 等 |
权限字符串文法与各资源上的语义见 permissions。
事实源
- Server API spec:
agentbase-sdksv2.6.0specs/open-api3-latest-server.json(端点、scope、错误模型、限流标注)。 - Server SDK 生成物:
server-nodejs/server-javav2.6.0(service 与 method 命名)。 - 语义深度参考:
skills/ob-agentbase/references/authentication.md。