REST-API – Übersicht
Aurabase rohe HTTP-Oberfläche. Kompatibel mit allen Sprachen. Basis-URL, Authentifizierung, Antwortformat, Fehlercodes – dann Details nach Endpunkt in /docs/api/.
Ein Ursprung, das Projekt auf dem Weg#
Die URL ist das Projekt. Jedes Projekt wird in seiner eigenen Subdomäne https://<slug>.<apex> (lokal http://<slug>.localhost:8080) bereitgestellt und das Gateway löst das Projekt vom Host auf: In den Pfaden wird keine Projektkennung geschrieben. Studio › Einstellungen › Connection zeigt diese URL an und NEXT_PUBLIC_AURABASE_URL speichert sie. Das Gateway stellt zwei Pläne bereit: den Datenplan (SDK und Anwendungen, :8080 lokal) und den Verwaltungsplan (Studio und Verwaltung, :8090). Den Datenplanoberflächen wird /v1/db, /v1/auth, /v1/storage, /v1/realtime, /v1/functions, /v1/notifications, /v1/ai vorangestellt.
# NEXT_PUBLIC_AURABASE_URL = Projekt-URL (z. B. 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
Die Formulare, die die Projekt-UUID im Pfad tragen (/v1/db/{project_id}/sensors, /v1/auth/{project_id}/login, wie auf den Endpunkt-Referenzseiten), werden weiterhin auf der Projekt-URL und auch auf dem Bare-Gateway-Ursprung akzeptiert. Sie werden aus Kompatibilitätsgründen beibehalten: Bevorzugen Sie die oben genannten Formen, die nicht von der Kennung abhängen.
Die Streaming-Routen /v1/realtime/ws und /v1/realtime/sse werden so bereitgestellt, wie sie auf dem Projekthost vorhanden sind. Eine URL, die kein Projekt identifiziert (z. B. der Bare-Gateway-Ursprung ohne Projektkennung), wird als 400 abgelehnt.
Zwei Schlüssel, einer JWT#
anon_key– veröffentlichbar. Dient als API-Schlüssel für jede Anfrage. Headerapikey,X-API-Keyoder Parameter?apikey=– letzterer wird nur bei Echtzeit-Streams akzeptiert (/ws,/sse,/chat/stream); andernorts wird dies ausdrücklich abgelehnt.service_role_key– Geheimnis, RLS umgehen. Reserviert für das Backend.user_jwt– ausgestellt vonPOST /v1/auth/loginnach der Authentifizierung. KopfzeileAuthorization: Bearer.
# Anonymer Kunde (Gast)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
# Authentifizierter Client (Anspruchsbenutzer)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
-H "Authorization: Bearer <USER_JWT>"
# Backend (RLS Bypass)
-H "apikey: <AURABASE_SERVICE_ROLE_KEY>"
-H "Authorization: Bearer <AURABASE_SERVICE_ROLE_KEY>"
Angewandte Standards#
Content-Type: application/json– erforderlich bei POST/PATCH/PUT (außer Upload-Speicher inmultipart/form-data)Prefer: return=representation– gibt die erstellten oder geänderten Zeilen zurück;return=minimalfür eine Antwort ohne Text (204).Prefer: count=exactwird auf Aura-db-Mutationen (Header) gelesenContent-Range+Preference-Applied); Um sich auf eine Lesung zu verlassen, verwenden Sie die?count=exactParameterRange: 0-49– nur auf einem Postgres-Projekt, das von PostgREST bedient wird, das es selbst interpretiert. Der aura-db-Pfad (MongoDB-Projekt oder Postgres mit deaktiviertem PostgREST) ignoriert diesen-Header: Er liest nurlimitundoffset. Bevorzugen Sielimit/offset, die auf beiden Engines funktionierenIdempotency-Key– wird NICHT in der Datenbank gelesen. (POST /v1/db/…) schreibt: Zwei identische POSTs erstellen zwei Zeilen. Es wird nur vonPOST /v1/notifications/{project_id}/send(und/send/batch) und durch die Erstellung des Managementplan-API-Schlüssels (POST /v1/db/{project_id}/api-keys, 24-Stunden-Fenster) berücksichtigt.
Grenze + Offset#
# Nur tragbare Form – funktioniert auf beiden Motoren
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?order=id.asc&limit=50&offset=100
# Schlüsselsatz „von Hand“: Filtern Sie nach dem zuletzt gelesenen Schlüssel
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?id=gt.{last_id}&order=id.asc&limit=50
# ?cursor=: NUR aura-db (MongoDB oder Postgres ohne PostgREST).
# Bei PostgREST wird die Anfrage in 400 abgelehnt.
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?cursor={meta.next_cursor}&limit=50
Ohne limit gibt ein Lesevorgang höchstens 1000 Zeilen zurück – dies ist sowohl die Standardeinstellung als auch die harte Obergrenze. Wenn eine Abfrage tatsächlich mehr übereinstimmende Zeilen über den zurückgegebenen Slice hinaus aufweist, ist meta.has_more true (und false, wenn keine zusätzlichen Zeilen vorhanden sind oder der letzte Slice erreicht wurde); Fragen Sie nach count=exact, um auch meta.total zu erhalten.
Die Gesamtsumme wird je nach Engine nicht an derselben Stelle gelesen: Auf dem Aura-DB-Pfad trägt die Antwort den Header Content-Range: items 100-149/1247 (die Gesamtsumme hat den Wert *, wenn keine Zählung angefordert wurde); Auf dem Pfad PostgREST leitet das Gateway diesen Header nicht weiter und platziert die Summe in meta.total des JSON-Umschlags. Das Zählen erfolgt standardmäßig nie: Fordern Sie es mit dem Parameter ?count=exact (portable Form, vom Gateway auf dem Pfad PostgREST in Prefer übersetzt), ?count=planned oder ?count=estimated an.
Die OpenAPI-Beschreibung Ihres Projekts wird unter GET /v1/db/{project_id}/openapi.json (mit Ihrem apikey) bereitgestellt. Es wird aus dem Live-Schema generiert, sodass eine Tabelle, die Sie gerade erstellt haben, darin angezeigt wird.
Einheitliches Format#
error ist immer ein Objekt, niemals eine Zeichenfolge. Je nach Aussteller gibt es zwei Varianten: Die Felder code und message sind beiden gemeinsam, und wir unterscheiden nach code (niemals nach message, Freitext).
{
"error": {
"type": "auth_unauthorized", // Maschinentyp, mit Präfix der Domäne
"code": "UNAUTHORIZED", // stabiler Code
"message": "Unauthorized: Invalid or revoked API key",
"request_id": "dc20e246-d8e0-412c-b9d7-ce675af6edd5"
}
}
{
"error": {
"code": "COLUMN_NOT_FOUND", // niemals der rohe PGRST-Code
"message": "Column unknown_col not found in table sensors",
"details": ""
}
}
PostgREST/PostgreSQL Codes (PGRST116, 23505…) werden nie so wie sie sind von der REST-API zurückgegeben: Das Gateway übersetzt sie in Aurabase Codes (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, sonst POSTGREST_ERROR). Diese Variante trägt kein type; Fehler, die vom Aufrufer behoben werden können, fügen einen hint hinzu (eine fehlende Spalte oder Funktion schlägt den nächstgelegenen Namen vor, eine RLS-Verweigerung ergibt den hinzuzufügenden create policy). Das JavaScript SDK behält PGRST116 für .single() / .maybeSingle() absichtlich bei, um die Kompatibilität mit supabase-js zu gewährleisten: Bei unformatiertem HTTP ist die gleiche Situation NOT_SINGULAR.
| Code | Name | Beschreibung |
|---|---|---|
400 | Schlechte Anfrage | Fehlerhafte Nutzlast oder Abfrage. error.code ist BAD_REQUEST. |
401 | Nicht autorisiert | Fehlende oder widerrufene apikey oder ungültige JWT. error.code ist UNAUTHORIZED oder REFRESH_TOKEN_REJECTED auf /refresh. |
403 | Verboten | RLS oder der Autorisierungsdienst lehnt den Vorgang ab. error.code ist FORBIDDEN, QUOTA_EXCEEDED oder INSUFFICIENT_PRIVILEGE (PostgREST Pfad). |
404 | Nicht gefunden | Die Ressource existiert nicht oder RLS verbirgt sie. error.code ist NOT_FOUND, RECORD_NOT_FOUND oder TABLE_NOT_FOUND. |
406 | Nicht akzeptabel | Eine Zeile erwartet, mehrere zurückgegeben. error.code ist NOT_SINGULAR. |
409 | Konflikt | Verletzung eines eindeutigen Schlüssels oder Fremdschlüssels. error.code ist CONFLICT, DUPLICATE_KEY oder FOREIGN_KEY_VIOLATION. Verwenden Sie on_conflict für einen Upsert. |
413 | Nutzlast zu groß | Anfrage größer als MAX_BODY_SIZE (standardmäßig 50 MB auf dem Gateway). Verwenden Sie einen mehrteiligen Speicher-Upload. |
429 | Zu viele Anfragen | Ratenlimit erreicht. error.code is RATE_LIMITED; message benennt das erreichte Limit (IP, Projekt oder API-Schlüssel) und hint gibt an, wann es erneut versucht werden soll. Die Header X-RateLimit-Limit und X-RateLimit-Remaining werden gesetzt und Retry-After bei Gateway-Ablehnungen. |
500 | Interner Serverfehler | Serverfehler. Geben Sie error.request_id zur Unterstützung. |
503 | Dienst nicht verfügbar | SERVER_BUSY, wenn das Gateway Last verliert (zu viele Anfragen im Flug, Retry-After: 1), DB_POOL_TIMEOUT, wenn der Verbindungspool des Projekts ausgelastet blieb, der Leistungsschalter offen war, eine Instanz fehlt oder das Projekt im Ruhezustand war (Retry-After: 5 in diesem Fall). Der Leistungsschalter versucht es nach 30 Sekunden erneut. |
504 | Gateway-Timeout | Upstream-Timeout. error.code ist TIMEOUT oder STATEMENT_TIMEOUT, wenn eine SQL-Anweisung länger als das 10-Sekunden-Anweisungszeitlimit des Projekts ausgeführt wurde. |
Per IP am Gateway, plus Limits pro Route#
- Pro Projekt und API-Schlüssel: die Grenze des Projektplans (Studio › Einstellungen › Nutzung). Ein
429benennt den betroffenen Bereich, sodass Sie wissen, ob Sie langsamer fahren oder ein Upgrade durchführen müssen. - Gateway, alle Routen: pro IP,
100req/s mit einem Burst von1000standardmäßig (einstellbar überRATE_LIMIT_RPS/RATE_LIMIT_BURST). Es gibt keine separate Ebene pro Rolle. - Authentifizierungssensitiv (
login,register,forgot-password,magic-link,email-otp/send,sms/send,refresh,mfa/verify-login): 5 Anforderungen/Minute pro IP, Burst 3. Zusätzlich ein Kontingent pro Projekt: 30 Verbindungen Versuche/Stunde pro IP standardmäßig, einstellbar in den Projekteinstellungen. In der Entwicklung (AURA_ENV=development, der lokale Stack) ist das Router-Limit gelockert (Burst 100), sodass Sie iterieren können; Es gelten immer die unter Studio › Authentifizierung › Konfiguration › Ratenbegrenzung angezeigten Projektkontingente. - Raw SQL (
/raw): 30 Anforderungen/Min., Burst 10. IA: 10 Anforderungen/Min., Burst 5.
Überlauf → 429 Too Many Requests mit den Headern X-RateLimit-Limit und X-RateLimit-Remaining (bei jeder Antwort vom Gateway vorhanden), plus X-RateLimit-Reset und Retry-After bei der Ablehnung.
Vollständiger Baum pro Service#
Jeder Endpunkt verfügt über eine eigene Seite mit Parametern, Antwortcodes, Beispielen in 5 Sprachen und Live-Rail-Code.
DatenbankAuthSpeicherEchtzeitFunktionen
Noch kein SDK für Ihre Sprache#
Es gibt noch kein veröffentlichtes Python- oder Dart-Paket (das sagt das Studio auch). Die obige REST-API ist vollständig, sodass ein Client nur wenige Zeilen umfasst. Die Python-Version verwendet nur die Standardbibliothek; Es liest die gleichen Variablen wie die anderen Beispiele und wandelt einen API-Fehler in eine Ausnahme um, die den stabilen code und den request_id trägt:
import json, os, urllib.error, urllib.request
URL = os.environ["NEXT_PUBLIC_AURABASE_URL"]
KEY = os.environ["NEXT_PUBLIC_AURABASE_ANON_KEY"] # oder AURABASE_SERVICE_ROLE_KEY auf einem Server
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"))
Die Dart-Version (Flutter oder Server) benötigt ebenfalls kein Paket; Führen Sie es mit dart run aurabase_rest.dart aus:
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'));
}