REST API — 概述
Aurabase 原始 HTTP 表面。兼容所有语言。基本 URL、身份验证、响应格式、错误代码 — 然后按 /docs/api/ 中的端点详细信息。
一个起源,一个在路上的项目#
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。
# 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。
# 匿名客户(来宾)
-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 小时窗口)来兑现它
限制+偏移#
# 仅便携式形式 - 适用于两种引擎
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,自由文本)。
{
"error": {
"type": "auth_unauthorized", // 机器类型,以域为前缀
"code": "UNAUTHORIZED", // 稳定的代码
"message": "Unauthorized: Invalid or revoked API key",
"request_id": "dc20e246-d8e0-412c-b9d7-ce675af6edd5"
}
}
{
"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,
100req/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的异常:
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运行它:
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'));
}