AppBase 云控制台
浏览全部文档 · 30/37
已支持已进入 main

REST API 与认证

SDK、REST、GraphQL 与错误处理

版本验证信息发布状态与验证 Commit
发布状态
已进入 main
后端验证 Commit
0363062a1c7ea08741975bb5ba0c3361663c9353

功能简介

AppBase 核心服务通过 /v1 REST API 暴露。每个 Action 独立声明 HTTP method/path、AuthType、Scope、参数校验、响应 Model 与事件/审计标签；调用者不能把某个接口接受 API Key 推广到所有接口。

当前支持范围

  • REST API（SUPPORTED）：核心服务通过版本化 REST API 暴露，每个接口单独声明认证类型、Scope 与响应模型。

适用场景

  • 在没有目标语言 SDK 时直接接入 HTTP。
  • 调试 SDK 实际发送的 method、path 与 payload。
  • 为服务端集成设置精确 Scope 和超时。

前置条件

  • 知道目标 endpoint 与 Project ID。
  • 选择该 Action 允许的 Session、JWT、API Key 或 Admin 身份。
  • 按 Content-Type 编码 JSON、multipart 或 query 参数。

Console 操作路径

Console 中的 API Reference/集成页面可辅助获取 Project 信息；控制面接口和数据面接口分别在对应服务页面操作。不要把浏览器 Network 中的 Console Cookie 复制到服务端脚本。

SDK 示例

SDK · TypeScript
import { Client, TablesDB } from 'appbase-node-sdk';

const client = new Client()
  .setEndpoint('https://<APPBASE_HOST>/v1')
  .setProject('<PROJECT_ID>')
  .setKey('<API_KEY>');

const tables = new TablesDB(client);
const rows = await tables.listRows({
  databaseId: '<DATABASE_ID>',
  tableId: '<TABLE_ID>',
  queries: []
});

REST 示例

REST · Bash
curl 'https://<APPBASE_HOST>/v1/tablesdb/<DATABASE_ID>/tables/<TABLE_ID>/rows' \
  -H 'X-Appwrite-Project: <PROJECT_ID>' \
  -H 'X-Appwrite-Key: <API_KEY>' \
  -H 'X-Appwrite-Response-Format: 1.9.0'

权限模型

Session/JWT 代表用户并受资源 Permission 约束；API Key 代表服务端应用并受 Scope 约束；Console Session 用于组织和项目控制面。Project header 选择上下文，但不授予权限。

常见错误

现象处理建议
400 general_argument_invalid根据 Action 参数定义修正 JSON/query/form，不用字符串猜测错误。
401 user_unauthorized目标 Action 不接受当前身份，或凭据已失效。
403 general_access_forbidden认证成功但 Scope/Role/Permission 不足。
404资源不存在或不可见；客户端按公开错误码处理。
500/503保留基础设施错误并按幂等性重试，不归一化成业务 not found。

当前限制

  • REST 接口覆盖面大于任一单一 SDK，但仍以当前 Commit 的 Action 为准。
  • 错误 message 不是稳定程序契约；优先使用 status、type/code 和结构化字段。
  • 开发环境的安全 Trace 不包含运行时 args；生产响应不新增 Trace。

Appwrite 兼容说明

REST /v1、Project Header 与常见认证头保持兼容；AppBase 自有 Action 仍遵循同一结构化声明方式。

AppBase 增强说明

AppBase 增强接口复用统一认证、Scope、响应 Model、审计和错误映射，而不是建立旁路鉴权。

发布状态和验证 Commit

origin/main 已核验。验证 Commit：0363062a1c7ea08741975bb5ba0c3361663c9353。

权威来源文件列表

  • backend-candidate:app/controllers/api/
  • backend-candidate:docs/references/
  • backend-candidate:src/Appwrite/Platform/Modules/*/Http/

Appwrite taxonomy 仅作信息架构参考：https://appwrite.io/docs/apis/rest。上游页面不是 AppBase 实现证据。

继续阅读