Zum Inhalt springen
Aurabase-Logo
Aurabasis

REST-API – Übersicht

Aurabase rohe HTTP-Oberfläche. Kompatibel mit allen Sprachen. Basis-URL, Authentifizierung, Antwortformat, Fehlercodes – dann Details nach Endpunkt in /docs/api/.

Referenz7 Min. gelesenEbene ReferenzÜberarbeitet am 15.04.2026

Diese Seite wurde automatisch übersetzt. Maßgeblich ist die englische Version.

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.

examplesbash
# 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
Infos

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.

Achtung

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. Header apikey, X-API-Key oder 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 von POST /v1/auth/login nach der Authentifizierung. Kopfzeile Authorization: Bearer.
headers.shbash
# 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 in multipart/form-data)
  • Prefer: return=representation – gibt die erstellten oder geänderten Zeilen zurück; return=minimal für eine Antwort ohne Text (204). Prefer: count=exact wird auf Aura-db-Mutationen (Header) gelesen Content-Range + Preference-Applied); Um sich auf eine Lesung zu verlassen, verwenden Sie die ?count=exact Parameter
  • Range: 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 nur limit und offset. Bevorzugen Sie limit/offset, die auf beiden Engines funktionieren
  • Idempotency-Key – wird NICHT in der Datenbank gelesen. (POST /v1/db/…) schreibt: Zwei identische POSTs erstellen zwei Zeilen. Es wird nur von POST /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#

pagination.shbash
# 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
Tipp

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.

Achtung

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).

Fehler, der von einem Aurabase-Dienst ausgegeben wirdjson
{
  "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"
  }
}
Vom Gateway übersetzter Fehler PostgRESTjson
{
  "error": {
    "code": "COLUMN_NOT_FOUND",    // niemals der rohe PGRST-Code
    "message": "Column unknown_col not found in table sensors",
    "details": ""
  }
}
Achtung

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.

CodeNameBeschreibung
400Schlechte AnfrageFehlerhafte Nutzlast oder Abfrage. error.code ist BAD_REQUEST.
401Nicht autorisiertFehlende oder widerrufene apikey oder ungültige JWT. error.code ist UNAUTHORIZED oder REFRESH_TOKEN_REJECTED auf /refresh.
403VerbotenRLS oder der Autorisierungsdienst lehnt den Vorgang ab. error.code ist FORBIDDEN, QUOTA_EXCEEDED oder INSUFFICIENT_PRIVILEGE (PostgREST Pfad).
404Nicht gefundenDie Ressource existiert nicht oder RLS verbirgt sie. error.code ist NOT_FOUND, RECORD_NOT_FOUND oder TABLE_NOT_FOUND.
406Nicht akzeptabelEine Zeile erwartet, mehrere zurückgegeben. error.code ist NOT_SINGULAR.
409KonfliktVerletzung 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.
413Nutzlast zu großAnfrage größer als MAX_BODY_SIZE (standardmäßig 50 MB auf dem Gateway). Verwenden Sie einen mehrteiligen Speicher-Upload.
429Zu viele AnfragenRatenlimit 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.
500Interner ServerfehlerServerfehler. Geben Sie error.request_id zur Unterstützung.
503Dienst nicht verfügbarSERVER_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.
504Gateway-TimeoutUpstream-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 429 benennt den betroffenen Bereich, sodass Sie wissen, ob Sie langsamer fahren oder ein Upgrade durchführen müssen.
  • Gateway, alle Routen: pro IP, 100 req/s mit einem Burst von 1000 standardmäßig (einstellbar über RATE_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.
Achtung

Ü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:

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"]  # 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:

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'));
}

Um weiter zu gehen#