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/.
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.
# 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
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.
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łówekapikey,X-API-Keylub 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 przezPOST /v1/auth/loginpo uwierzytelnieniu. NagłówekAuthorization: Bearer.
# 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 wmultipart/form-data)Prefer: return=representation— zwraca utworzone lub zmodyfikowane wiersze;return=minimaldla odpowiedzi bez treści (204).Prefer: count=exactjest odczytywany na mutacjach aura-db (nagłówkiContent-Range+Preference-Applied); Aby polegać na odczycie , użyj parametru?count=exactRange: 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 tylkolimitioffset. Preferujlimit/offset, które działają na obu silnikachIdempotency-Key— NIE jest czytany w bazie danych (POST /v1/db/…) zapisuje: dwa identyczne POSTy tworzą dwa wiersze. Jest honorowany jedynie przezPOST /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#
# 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
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.
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.
{
"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"
}
}
{
"error": {
"code": "COLUMN_NOT_FOUND", // nigdy surowy kod PGRST
"message": "Column unknown_col not found in table sensors",
"details": ""
}
}
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.
| Kod | Nazwa | Opis |
|---|---|---|
400 | Złe żądanie | Zniekształcony ładunek lub zapytanie. error.code to BAD_REQUEST. |
401 | Nieautoryzowane | Brakujący lub odwołany apikey lub nieprawidłowy JWT. error.code to UNAUTHORIZED lub REFRESH_TOKEN_REJECTED na /refresh. |
403 | Zabroniony | RLS lub usługa autoryzacji odmawia operacji. error.code to FORBIDDEN, QUOTA_EXCEEDED lub INSUFFICIENT_PRIVILEGE (ścieżka PostgREST). |
404 | Nie znaleziono | Zasób nie istnieje lub RLS go ukrywa. error.code to NOT_FOUND, RECORD_NOT_FOUND lub TABLE_NOT_FOUND. |
406 | Nie do przyjęcia | Oczekiwano jednego rzędu, kilka wróciło. error.code to NOT_SINGULAR. |
409 | Konflikt | Naruszenie 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. |
429 | Zbyt 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. |
500 | Wewnętrzny błąd serwera | Błąd serwera. Daj error.request_id do wsparcia. |
503 | Usługa niedostępna | SERVER_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. |
504 | Limit czasu bramy | Przekroczono 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).
429nazywa zakres, który został trafiony, więc wiesz, czy zwolnić, czy zaktualizować. - Brama, wszystkie trasy: na adres IP,
100żądanie/s z serią1000domyś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.
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:
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:
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'));
}