Przejdź do treści
Logo Aurabase
aurabaza

API REST — przegląd

Aurabase surowa powierzchnia HTTP. Kompatybilny ze wszystkimi językami. Podstawowy adres URL, uwierzytelnianie, format odpowiedzi, kody błędów — następnie szczegóły według punktu końcowego w /docs/api/.

Referencja7 min przeczytanePoziom odniesienieZmieniono 15 kwi 2026

Ta strona została przetłumaczona automatycznie. Wersja angielska jest miarodajna.

Początki, projekt w drodze#

Adres URL to projektu. Każdy projekt jest obsługiwany we własnej subdomenie https://<slug>.<apex> (lokalnie http://<slug>.localhost:8080), a brama rozpoznaje projekt z hosta: w ścieżkach nie jest zapisany żaden identyfikator projektu. Studio > Ustawienia > Połączenie pokazuje ten adres URL, a NEXT_PUBLIC_AURABASE_URL go przechowuje. Brama udostępnia dwa plany: plan danych (SDK i aplikacje, :8080 lokalnie) i plan zarządzania (Studio i administracja, :8090). Powierzchnie planu danych mają prefiks /v1/db, /v1/auth, /v1/storage, /v1/realtime, /v1/functions, /v1/notifications, /v1/ai.

examplesbash
# NEXT_PUBLIC_AURABASE_URL = adres URL projektu (np. 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
Informacje

Formularze przenoszące w ścieżce identyfikator UUID projektu (/v1/db/{project_id}/sensors, /v1/auth/{project_id}/login jak na stronach referencyjnych punktów końcowych) są nadal akceptowane w adresie URL projektu, a także w pochodzeniu samej bramy. Są przechowywane ze względu na kompatybilność: preferuj powyższe formularze, które nie zależą od identyfikatora.

Uwaga

Trasy przesyłania strumieniowego /v1/realtime/ws i /v1/realtime/sse są obsługiwane w takiej postaci, w jakiej znajdują się na hoście projektu. Adres URL, który nie identyfikuje projektu (na przykład samo źródło bramy bez identyfikatora projektu) jest odrzucany jako 400.

Dwa klucze, jeden JWT#

  • anon_key — do publikacji. Służy jako klucz API dla każdego żądania. Nagłówek apikey, X-API-Key lub parametr ?apikey= — ten ostatni jest akceptowany tylko w przypadku strumieni czasu rzeczywistego (/ws, /sse, /chat/stream); gdzie indziej jest to wyraźnie odrzucone.
  • service_role_key — sekret, ominięcie RLS. Zarezerwowane dla backendu.
  • user_jwt — wystawiony przez POST /v1/auth/login po uwierzytelnieniu. Nagłówek Authorization: Bearer.
headers.shbash
# Klient anonimowy (gość)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"

# Uwierzytelniony klient (użytkownik twierdzi)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
-H "Authorization: Bearer <USER_JWT>"

# Backend (obejście RLS)
-H "apikey: <AURABASE_SERVICE_ROLE_KEY>"
-H "Authorization: Bearer <AURABASE_SERVICE_ROLE_KEY>"

Stosowane standardy#

  • Content-Type: application/json — wymagane podczas POST/PATCH/PUT (z wyjątkiem przechowywania danych w multipart/form-data)
  • Prefer: return=representation — zwraca utworzone lub zmodyfikowane wiersze; return=minimal dla odpowiedzi bez treści (204). Prefer: count=exact jest odczytywany na mutacjach aura-db (nagłówki Content-Range + Preference-Applied); Aby polegać na odczycie , użyj parametru ?count=exact
  • Range: 0-49 — tylko w projekcie Postgres obsługiwanym przez PostgREST, który sam to interpretuje. Ścieżka aura-db (projekt MongoDB lub Postgres z wyłączoną PostgREST) ignoruje ten nagłówek: czyta tylko limit i offset. Preferuj limit/offset, które działają na obu silnikach
  • Idempotency-Key — NIE jest czytany w bazie danych (POST /v1/db/…) zapisuje: dwa identyczne POSTy tworzą dwa wiersze. Jest honorowany jedynie przez POST /v1/notifications/{project_id}/send (i /send/batch) oraz poprzez utworzenie klucza API planu zarządzania (POST /v1/db/{project_id}/api-keys, okno 24-godzinne)

Limit + przesunięcie#

pagination.shbash
# Tylko forma przenośna — działa na obu silnikach
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?order=id.asc&limit=50&offset=100

# Zestaw kluczy „ręcznie”: filtruj według ostatniego odczytanego klucza
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?id=gt.{last_id}&order=id.asc&limit=50

# ?cursor=: TYLKO aura-db (MongoDB lub Postgres bez PostgREST).
# W dniu PostgREST żądanie zostało odrzucone w 400.
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?cursor={meta.next_cursor}&limit=50
Wskazówka

Bez limit odczyt zwraca co najwyżej 1000 wierszy — jest to zarówno ustawienie domyślne, jak i twardy pułap. Gdy zapytanie faktycznie zawiera więcej pasujących wierszy poza zwróconym wycinkiem, meta.has_more wynosi true (i false, jeśli nie ma żadnych dodatkowych wierszy lub osiągnięto ostatni wycinek); poproś o count=exact, aby otrzymać również meta.total.

Uwaga

Suma nie jest odczytywana w tym samym miejscu, w zależności od silnika: na ścieżce aura-db odpowiedź zawiera nagłówek Content-Range: items 100-149/1247 (suma jest warta *, jeśli nie zażądano zliczenia); na ścieżce PostgREST brama nie przekazuje tego nagłówka i umieszcza sumę w meta.total koperty JSON. Zliczanie nigdy nie jest wykonywane domyślnie: zażądaj tego z parametrem ?count=exact (forma przenośna, tłumaczona na Prefer przez bramę na ścieżce PostgREST), ?count=planned lub ?count=estimated.

Opis OpenAPI Twojego projektu jest dostępny pod adresem GET /v1/db/{project_id}/openapi.json (z Twoim apikey); jest on generowany na podstawie aktywnego schematu, więc pojawia się w nim właśnie utworzona tabela.

Jednolity format#

error jest zawsze obiektem, nigdy ciągiem znaków. Dwa warianty, w zależności od emitenta - pola code i message są wspólne dla obu i to właśnie na code (nigdy na message, tekst dowolny) rozróżniamy.

błąd emitowany przez usługę Aurabasejson
{
  "error": {
    "type": "auth_unauthorized",      // typ komputera, poprzedzony domeną
    "code": "UNAUTHORIZED",         // stabilny kod
    "message": "Unauthorized: Invalid or revoked API key",
    "request_id": "dc20e246-d8e0-412c-b9d7-ce675af6edd5"
  }
}
Błąd PostgREST przetłumaczony przez bramęjson
{
  "error": {
    "code": "COLUMN_NOT_FOUND",    // nigdy surowy kod PGRST
    "message": "Column unknown_col not found in table sensors",
    "details": ""
  }
}
Uwaga

Kody PostgREST/PostgreSQL (PGRST116, 23505…) są nigdy nie zwracane w takiej postaci, w jakiej jest to API REST: bramka tłumaczy je na kody 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, w przeciwnym razie POSTGREST_ERROR). Ten wariant nie zawiera type; błędy, które może naprawić osoba wywołująca, dodaj hint (brakująca kolumna lub funkcja sugeruje najbliższą nazwę, odmowa RLS powoduje dodanie create policy). Zestaw JavaScript SDK celowo przechowuje PGRST116 dla .single() / .maybeSingle(), aby zachować zgodność z supabase-js: na surowym HTTP ta sama sytuacja ma miejsce NOT_SINGULAR.

KodNazwaOpis
400Złe żądanieZniekształcony ładunek lub zapytanie. error.code to BAD_REQUEST.
401NieautoryzowaneBrakujący lub odwołany apikey lub nieprawidłowy JWT. error.code to UNAUTHORIZED lub REFRESH_TOKEN_REJECTED na /refresh.
403ZabronionyRLS lub usługa autoryzacji odmawia operacji. error.code to FORBIDDEN, QUOTA_EXCEEDED lub INSUFFICIENT_PRIVILEGE (ścieżka PostgREST).
404Nie znalezionoZasób nie istnieje lub RLS go ukrywa. error.code to NOT_FOUND, RECORD_NOT_FOUND lub TABLE_NOT_FOUND.
406Nie do przyjęciaOczekiwano jednego rzędu, kilka wróciło. error.code to NOT_SINGULAR.
409KonfliktNaruszenie unikalnego lub obcego klucza. error.code to CONFLICT, DUPLICATE_KEY lub FOREIGN_KEY_VIOLATION. Użyj on_conflict dla podwyżki.
413Ładunek zbyt dużyŻądanie większe niż MAX_BODY_SIZE (domyślnie 50 MB na bramce). Użyj wieloczęściowego przesyłania do magazynu.
429Zbyt wiele żądańOsiągnięto limit stawki. error.code to RATE_LIMITED; message określa osiągnięty limit (adres IP, klucz projektu lub API), a hint mówi, kiedy ponowić próbę. Nagłówki X-RateLimit-Limit i X-RateLimit-Remaining są ustawione, a Retry-After w przypadku odmów bramy.
500Wewnętrzny błąd serweraBłąd serwera. Daj error.request_id do wsparcia.
503Usługa niedostępnaSERVER_BUSY, gdy brama zmniejsza obciążenie (zbyt wiele żądań w locie, Retry-After: 1), DB_POOL_TIMEOUT, gdy pula połączeń projektu pozostaje nasycona, wyłącznik automatyczny jest otwarty, brakuje instancji lub projekt znajduje się w stanie hibernacji (w tym przypadku Retry-After: 5). Wyłącznik podejmuje ponowną próbę po 30 sekundach.
504Limit czasu bramyPrzekroczono limit czasu w górę. error.code to TIMEOUT lub STATEMENT_TIMEOUT, gdy instrukcja SQL działała dłużej niż 10-sekundowy limit czasu instrukcji projektu.

Według adresu IP na bramie plus limity na trasę#

  • Na projekt i klucz API: limit planu projektu (Studio > Ustawienia > Użycie). 429 nazywa zakres, który został trafiony, więc wiesz, czy zwolnić, czy zaktualizować.
  • Brama, wszystkie trasy: na adres IP, 100 żądanie/s z serią 1000 domyślnie (regulowane za pomocą RATE_LIMIT_RPS / RATE_LIMIT_BURST). Nie ma oddzielnego poziomu dla każdej roli.
  • Czułe uwierzytelnianie (login, register, forgot-password, magic-link, email-otp/send, sms/send, refresh, mfa/verify-login): 5 żądań/min na adres IP, seria 3. Dodatkowo limit na projekt: 30 połączeń domyślnie próby/godzinę na adres IP, regulowane w ustawieniach projektu. W fazie rozwoju (AURA_ENV=development, stos lokalny) limit routera jest rozluźniony (seria 100), dzięki czemu można iterować; zawsze obowiązują limity projektu pokazane w Studio > Uwierzytelnianie > Konfiguracja > Ograniczenie szybkości.
  • Surowy SQL (/raw): 30 żądań/min, seria 10. IA: 10 żądań/min, seria 5.
Uwaga

Przepełnienie → 429 Too Many Requests z nagłówkami X-RateLimit-Limit i X-RateLimit-Remaining (obecne w każdej odpowiedzi z bramki) plus X-RateLimit-Reset i Retry-After w przypadku odmowy.

Kompletne drzewo na usługę#

Każdy punkt końcowy ma swoją dedykowaną stronę z parametrami, kodami odpowiedzi, przykładami w 5 językach i aktualnym kodem kolejowym.

Baza danychAuthPamięćCzas rzeczywistyFunkcje

Nie ma jeszcze pakietu SDK dla Twojego języka#

Nie opublikowano jeszcze pakietu Python ani Dart (tak twierdzi także Studio). Powyższy interfejs API REST jest kompletny, więc klient to kilka linijek. Wersja Pythona korzysta tylko ze standardowej biblioteki; odczytuje te same zmienne, co w innych przykładach i zamienia błąd API w wyjątek, który zawiera stabilne code i 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"]  # lub AURABASE_SERVICE_ROLE_KEY na serwerze


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

Wersja Dart (Flutter lub serwer) również nie wymaga pakietu; uruchom go za pomocą 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'));
}

Aby pójść dalej#