GraphQL API
以 GraphQL 查询/变更访问平台数据面:查询语法与 REST 数据模型一致。
资源与基础路径
- Base URL:
https://<your-endpoint>/v1。 - 路径前缀
/graphql;无状态端点。
认证与权限
认证与请求头约定见 通用约定。
- scope:
graphql;限流 60 次/分钟。
端点清单
| 方法 + 路径 | 用途 |
|---|---|
POST /graphql | GraphQL 查询 |
POST /graphql/mutation | GraphQL 变更 |
请求与响应
以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。标注「泛化 schema any」的端点,响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准。
GraphQL
POST /v1/graphql
执行 GraphQL 查询:body 为标准 GraphQL query / variables 文档,schema 覆盖各域 REST 的等价读取操作。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
query | body | string | 是 | — | GraphQL 文档字符串(查询或变更)。平台 GraphQL schema 覆盖各域 REST 的等价操作;spec 未展开 body schema,具体字段以当前项目 schema 为准。 |
variables | body | object | 否 | — | 文档变量对象,与文档中的 $var 占位对应。 |
operationName | body | string | 否 | — | 多操作文档中要执行的操作名。 |
输出:返回 200 + 标准 GraphQL 响应:data(结果)与/或 errors(错误数组)。GraphQL 层错误不产生非 2xx 状态码,调用方必须检查 errors 字段。
- 限流 60 次/分钟(与 REST 计入同一项目限流体系)。
- 以下示例展示调用形态;具体 schema 字段以当前项目 GraphQL schema 为准。
调用示例:
curl -X POST "https://<your-endpoint>/v1/graphql" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"query": "query GetUserName { account { name email } }",
"variables": {}
}'响应示例:
{
"data": {
"account": {
"name": "Docs Bot",
"email": "bot@example.com"
}
}
}POST /v1/graphql/mutation
执行 GraphQL 变更:body 为标准 GraphQL mutation 文档,schema 覆盖各域 REST 的等价写入操作。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
query | body | string | 是 | — | GraphQL 文档字符串(查询或变更)。平台 GraphQL schema 覆盖各域 REST 的等价操作;spec 未展开 body schema,具体字段以当前项目 schema 为准。 |
variables | body | object | 否 | — | 文档变量对象,与文档中的 $var 占位对应。 |
operationName | body | string | 否 | — | 多操作文档中要执行的操作名。 |
输出:返回 200 + 标准 GraphQL 响应(data / errors)。
- 限流 60 次/分钟;变更同样把错误放在
errors字段内返回。 - 以下示例展示调用形态;具体 schema 字段以当前项目 GraphQL schema 为准。
调用示例:
curl -X POST "https://<your-endpoint>/v1/graphql/mutation" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"query": "mutation CreateTeam($id: String!, $name: String!) { teamsCreate(teamId: $id, name: $name) { _id name } }",
"variables": { "id": "team_docs", "name": "Docs" }
}'响应示例:
{
"data": {
"teamsCreate": {
"_id": "team_docs",
"name": "Docs"
}
}
}错误与边界
- GraphQL 与 REST 计入同一项目限流体系;GraphQL
errors不产生 HTTP 错误码,调用方需检查响应体。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
Graphql.query / mutation | POST /graphql、POST /graphql/mutation |
事实源
- Server API spec:
agentbase-sdksv2.6.0specs/open-api3-latest-server.json。 - Server SDK 生成物:
server-nodejs/server-javav2.6.0 同名 service。 - 语义深度参考:
skills/ob-agentbase/references/environment-context.md。