REST API — 概要
Aurabase 生の HTTP サーフェス。すべての言語に対応しています。ベース URL、認証、応答形式、エラー コード - /docs/api/ のエンドポイントごとの詳細。
原点、途中のプロジェクト#
URL は プロジェクトです。各プロジェクトは独自のサブドメイン https://<slug>.<apex> (ローカルでは http://<slug>.localhost:8080) で提供され、ゲートウェイはホストからプロジェクトを解決します。パスにはプロジェクト識別子は書き込まれません。 Studio › 設定 › 接続 にこの URL が表示され、NEXT_PUBLIC_AURABASE_URL がそれを保持します。ゲートウェイは、データ プラン (SDK とアプリケーション、ローカルの :8080 ) と管理プラン (スタジオと管理、 :8090) の 2 つのプランを公開します。データ プラン サーフェスには、 /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として拒否されます。
キー 2 つ、JWT 1 つ#
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/…) の書き込み: 2 つの同一の POST は 2 つの行を作成します。これは、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 になります)。 meta.totalも取得するには、 count=exact を要求します。
エンジンによっては、合計が同じ場所で読み取られません。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 は常にオブジェクトであり、文字列ではありません。発行者に応じた 2 つのバリアント - フィールド 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 は、 supabase-jsとの互換性のために、意図的に .single() / .maybeSingle() の PGRST116 を保持します。生の 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 | 受け入れられない | 1 行が予期されていましたが、複数の行が返されました。 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 キーごと: プロジェクトの計画の制限 (スタジオ › 設定 › 使用法)。
429はヒットしたスコープに名前を付けるため、速度を落とすかアップグレードするかを判断できます。 - ゲートウェイ、すべてのルート: IP ごとに、デフォルトで
1000のバーストを含む100要求/秒 (RATE_LIMIT_RPS/RATE_LIMIT_BURST経由で調整可能)。役割ごとに個別の階層はありません。 - 認証に敏感な (
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 › Authentication › Configuration › Rate Limiting に表示されるプロジェクト クォータは常に適用されます。 - Raw SQL (
/raw): 30 要求/分、バースト 10。 IA: 10 要求/分、バースト 5。
オーバーフロー → ヘッダー X-RateLimit-Limit および X-RateLimit-Remaining (ゲートウェイからの応答に存在) を含む 429 Too Many Requests、および拒否時の 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'));
}