跳到内容
光环标志
光环基地

REST API — 概述

Aurabase 原始 HTTP 表面。兼容所有语言。基本 URL、身份验证、响应格式、错误代码 — 然后按 /docs/api/ 中的端点详细信息。

参考7分钟 读取级别 参考修改于 2026年4月15日

该页面已自动翻译。英文版具有权威性。

一个起源,一个在路上的项目#

URL 是项目的。每个项目都在其自己的子域 https://<slug>.<apex> (本地 http://<slug>.localhost:8080)上提供服务,并且网关从主机解析项目:路径中不写入项目标识符。 Studio › 设置 › 连接显示此 URL,NEXT_PUBLIC_AURABASE_URL 保留它。网关公开两个计划:数据计划(SDK 和应用程序,本地 :8080 )和管理计划(Studio 和管理,:8090)。数据计划表面的前缀为 /v1/db、 /v1/auth、 /v1/storage、 /v1/realtime、 /v1/functions、 /v1/notifications、 /v1/ai。

examplesbash
# NEXT_PUBLIC_AURABASE_URL = 项目 URL(例如 http://my-app-x1y2z3.localhost:8080)

GET   $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors
POST  $NEXT_PUBLIC_AURABASE_URL/v1/auth/login
GET   $NEXT_PUBLIC_AURABASE_URL/v1/storage/avatars/u_xx/file.png
POST  $NEXT_PUBLIC_AURABASE_URL/v1/functions/ocr/invoke
信息

路径中携带项目 UUID 的表单(/v1/db/{project_id}/sensors、 /v1/auth/{project_id}/login,如端点参考页面中所示)仍被项目 URL 以及裸网关源接受。保留它们是为了兼容性:更喜欢上面的形式,它不依赖于标识符。

注意

流路由 /v1/realtime/ws 和 /v1/realtime/sse 按其在项目主机上的方式提供。不标识项目的 URL(例如没有项目标识符的裸网关源)将被拒绝为 400。

两把钥匙,一把 JWT#

  • anon_key — 可发布。用作任何请求的 API 密钥。标头 apikey、 X-API-Key或参数 ?apikey= — 后者仅在实时流上接受(/ws、 /sse、 /chat/stream);其他地方则明确拒绝。
  • service_role_key — 秘密,RLS 绕过。为后端保留。
  • user_jwt — 身份验证后由 POST /v1/auth/login 颁发。标头 Authorization: Bearer。
headers.shbash
# 匿名客户(来宾)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"

# 经过身份验证的客户端(声明用户)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
-H "Authorization: Bearer <USER_JWT>"

# 后端(RLS 绕过)
-H "apikey: <AURABASE_SERVICE_ROLE_KEY>"
-H "Authorization: Bearer <AURABASE_SERVICE_ROLE_KEY>"

适用标准#

  • Content-Type: application/json — POST/PATCH/PUT 时需要(上传存储除外,在 multipart/form-data中)
  • Prefer: return=representation — 返回创建或修改的行; return=minimal 用于没有正文的响应 (204)。 Prefer: count=exact 在 aura-db 突变上读取(标头 Content-Range + Preference-Applied);要依赖 读取,请使用 ?count=exact 参数
  • Range: 0-49 — 仅在由 PostgREST提供服务的 Postgres 项目上 ,该项目本身对其进行解释。 aura-db 路径(MongoDB 项目,或禁用 PostgREST 的 Postgres ) 忽略此 标头:它只读取 limit 和 offset。更喜欢 limit/offset,它们适用于两个引擎
  • Idempotency-Key — 未在数据库 (POST /v1/db/…) 写入中读取:两个相同的 POST 创建两行。仅通过 POST /v1/notifications/{project_id}/send (和 /send/batch)以及创建管理计划 API 密钥(POST /v1/db/{project_id}/api-keys,24 小时窗口)来兑现它

限制+偏移#

pagination.shbash
# 仅便携式形式 - 适用于两种引擎
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?order=id.asc&limit=50&offset=100

# “手动”按键设置:过滤最后读取的按键
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?id=gt.{last_id}&order=id.asc&limit=50

# ?cursor=: 仅 aura-db (MongoDB 或不带 PostgREST的 Postgres )。
# 在 PostgREST 上,请求被拒绝,返回 400。
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?cursor={meta.next_cursor}&limit=50
提示

如果没有 limit,读取最多返回 1000 行 — 这既是默认值也是硬上限。当查询实际上有更多匹配行超出返回的切片时,meta.has_more 是 true(当不存在其他行或已到达最终切片时,false );要求 count=exact 也能获得 meta.total。

注意

根据引擎的不同,总数不会在同一位置读取:在 aura-db 路径上,响应携带标头 Content-Range: items 100-149/1247 (如果未请求计数,则总数值为 *);在 PostgREST 路径上,网关不会中继此标头,而是将总计放入 JSON 信封的 meta.total 中。默认情况下,永远不会进行计数:使用参数 ?count=exact (可移植形式,由 PostgREST 路径上的网关转换为 Prefer )、 ?count=planned或 ?count=estimated进行请求。

您的项目的 OpenAPI 描述位于 GET /v1/db/{project_id}/openapi.json (与您的 apikey);它是从实时模式生成的,因此您刚刚创建的表会出现在其中。

统一格式#

error 始终是一个对象,而不是字符串。有两种变体,具体取决于发行人 - 字段 code 和 message 对于两者来说都是通用的,并且我们区分的是 code (绝不是 message,自由文本)。

Aurabase 服务发出的错误json
{
  "error": {
    "type": "auth_unauthorized",      // 机器类型,以域为前缀
    "code": "UNAUTHORIZED",         // 稳定的代码
    "message": "Unauthorized: Invalid or revoked API key",
    "request_id": "dc20e246-d8e0-412c-b9d7-ce675af6edd5"
  }
}
PostgREST 网关转换的错误json
{
  "error": {
    "code": "COLUMN_NOT_FOUND",    // 绝不是原始 PGRST 代码
    "message": "Column unknown_col not found in table sensors",
    "details": ""
  }
}
注意

PostgREST/PostgreSQL 代码(PGRST116、 23505...)是 ,不会由 REST API 按原样返回 :网关将它们转换为 Aurabase 代码(RECORD_NOT_FOUND、 NOT_SINGULAR、 COLUMN_NOT_FOUND、 NO_RELATIONSHIP、 SCHEMA_NOT_FOUND、DUPLICATE_KEY、FOREIGN_KEY_VIOLATION、CHECK_VIOLATION、INVALID_INPUT、NUMERIC_OUT_OF_RANGE、INVALID_BODY、TABLE_NOT_FOUND、FUNCTION_NOT_FOUND、INSUFFICIENT_PRIVILEGE、STATEMENT_TIMEOUT、DB_POOL_TIMEOUT,否则为 POSTGREST_ERROR)。此变体不带有 type;可以由调用者修复的错误添加 hint (缺少的列或函数建议最接近的名称,RLS 拒绝给出要添加的 create policy)。 JavaScript SDK 故意为 .single() / .maybeSingle() 保留 PGRST116 ,以便与 supabase-js兼容:在原始 HTTP 上,相同的情况是 NOT_SINGULAR。

代码名称描述
400错误的请求有效负载或查询格式错误。 error.code 是 BAD_REQUEST。
401未经授权缺少或撤销 apikey,或无效 JWT。 error.code 是 UNAUTHORIZED,或 /refresh上的 REFRESH_TOKEN_REJECTED 。
403禁止RLS 或授权服务拒绝操作。 error.code 是 FORBIDDEN、 QUOTA_EXCEEDED 或 INSUFFICIENT_PRIVILEGE (PostgREST 路径)。
404未找到该资源不存在或 RLS 隐藏了它。 error.code 是 NOT_FOUND、 RECORD_NOT_FOUND 或 TABLE_NOT_FOUND。
406不可接受预计一排,几排返回。 error.code 是 NOT_SINGULAR。
409冲突唯一或外键违规。 error.code 是 CONFLICT、 DUPLICATE_KEY 或 FOREIGN_KEY_VIOLATION。使用 on_conflict 进行更新插入。
413有效负载太大请求大于 MAX_BODY_SIZE(网关上默认为 50 MB)。使用分段存储上传。
429请求过多已达到速率限制。 error.code 是 RATE_LIMITED; message 命名所达到的限制(IP、项目或 API 密钥),hint 表示何时重试。 设置 X-RateLimit-Limit 和 X-RateLimit-Remaining 标头,并在网关拒绝时设置 Retry-After。
500内部服务器错误服务器错误。给予 error.request_id 支持。
503服务不可用SERVER_BUSY 当网关卸载负载时(太多请求正在运行, Retry-After: 1),DB_POOL_TIMEOUT 当项目的连接池保持饱和、断路器打开、实例丢失或项目休眠时(在这种情况下为Retry-After: 5 )。断路器会在 30 秒后重试。
504网关超时上行超时。 当 SQL 语句运行时间超过项目的 10 秒语句超时时,error.code 为 TIMEOUT或 STATEMENT_TIMEOUT 。

通过网关的 IP,加上每条路由的限制#

  • 每个项目和 API 密钥:项目计划的限制(Studio › 设置 › 使用)。 429 命名了被击中的范围,因此您知道是否要放慢速度或升级。
  • 网关,所有路由:每个 IP,100 req/s,默认情况下突发 1000 (可通过 RATE_LIMIT_RPS / RATE_LIMIT_BURST调整)。每个角色没有单独的层级。
  • Auth 敏感 (login、 register、 forgot-password、 magic-link、 email-otp/send、 sms/send、 refresh、 mfa/verify-login):每个 IP 5 个请求/分钟,突发 3。此外,每个项目的配额:30 个连接默认情况下每个 IP 尝试/小时,可在项目设置中进行调整。在开发中(AURA_ENV=development,本地堆栈),路由器限制放宽(突发 100),因此您可以迭代; Studio › 身份验证 › 配置 › 速率限制中显示的项目配额始终适用。
  • 原始 SQL (/raw):30 个请求/分钟,突发 10 个。 IA:10 个请求/分钟,突发 5 个。
注意

溢出 → 429 Too Many Requests,带有标头 X-RateLimit-Limit 和 X-RateLimit-Remaining(出现在来自网关的任何响应上),加上拒绝时的 X-RateLimit-Reset 和 Retry-After。

每个服务的完整树#

每个端点都有其专用页面,其中包含参数、响应代码、5 种语言的示例和实时铁路代码。

数据库授权存储实时函数

还没有适合您的语言的 SDK#

目前还没有发布的 Python 或 Dart 包(工作室也这么说)。上面的REST API是完整的,所以一个客户端就几行。 Python版本仅使用标准库;它读取与其他示例相同的变量,并将 API 错误转换为携带稳定 code 和 request_id的异常:

aurabase_rest.pypython
import json, os, urllib.error, urllib.request

URL = os.environ["NEXT_PUBLIC_AURABASE_URL"]
KEY = os.environ["NEXT_PUBLIC_AURABASE_ANON_KEY"]  # 或服务器上的 AURABASE_SERVICE_ROLE_KEY


def get(path):
    request = urllib.request.Request(URL + path, headers={"apikey": KEY})
    try:
        with urllib.request.urlopen(request, timeout=15) as response:
            return json.load(response)
    except urllib.error.HTTPError as e:
        error = json.load(e)["error"]
        raise RuntimeError(f'{error["code"]}: {error["message"]} (request_id {error.get("request_id")})')


print(get("/v1/db/todos?limit=2"))

Dart版本(Flutter或服务器)也不需要包;使用 dart run aurabase_rest.dart运行它:

aurabase_rest.dartdart
import 'dart:convert';
import 'dart:io';

final url = Platform.environment['NEXT_PUBLIC_AURABASE_URL']!;
final key = Platform.environment['NEXT_PUBLIC_AURABASE_ANON_KEY']!; // or AURABASE_SERVICE_ROLE_KEY on a server

Future<dynamic> get(String path) async {
  final client = HttpClient();
  try {
    final request = await client.getUrl(Uri.parse(url + path));
    request.headers.set('apikey', key);
    final response = await request.close();
    final body = jsonDecode(await response.transform(utf8.decoder).join());
    if (response.statusCode >= 400) {
      final error = body['error'];
      throw Exception('${error['code']}: ${error['message']} (request_id ${error['request_id']})');
    }
    return body;
  } finally {
    client.close();
  }
}

Future<void> main() async {
  print(await get('/v1/db/todos?limit=2'));
}

为了走得更远#