REST API — Overzicht
Aurabase onbewerkt HTTP-oppervlak. Compatibel met alle talen. Basis-URL, authenticatie, antwoordformaat, foutcodes – en vervolgens details per eindpunt in /docs/api/.
Een oorsprong, het project onderweg#
De URL is het project. Elk project wordt aangeboden op zijn eigen subdomein, https://<slug>.<apex> (lokaal http://<slug>.localhost:8080), en de gateway lost het project op vanaf de host: er wordt geen project-ID in de paden geschreven. Studio › Instellingen › Connection toont deze URL, en NEXT_PUBLIC_AURABASE_URL bewaart deze. De gateway biedt twee plannen: het dataplan (SDK en applicaties, :8080 lokaal) en het beheerplan (Studio en beheer, :8090). De dataplanoppervlakken hebben het voorvoegsel /v1/db, /v1/auth, /v1/storage, /v1/realtime, /v1/functions, /v1/notifications, /v1/ai.
# NEXT_PUBLIC_AURABASE_URL = project-URL (bijvoorbeeld 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
De formulieren met de project-UUID in het pad (/v1/db/{project_id}/sensors, /v1/auth/{project_id}/login, zoals op de eindpuntreferentiepagina's) worden nog steeds geaccepteerd op de project-URL, en ook op de kale gateway-oorsprong. Ze worden bewaard voor compatibiliteit: geef de voorkeur aan de bovenstaande formulieren, die niet afhankelijk zijn van de identificatie.
De streamingroutes /v1/realtime/ws en /v1/realtime/sse worden aangeboden zoals ze zich op de projecthost bevinden. Een URL die een project niet identificeert (bijvoorbeeld de kale gateway-oorsprong zonder project-ID) wordt afgewezen als 400.
Twee sleutels, één JWT#
anon_key— publiceerbaar. Dient als API-sleutel voor elk verzoek. Headerapikey,X-API-Keyof parameter?apikey=— de laatste wordt alleen geaccepteerd op realtime streams (/ws,/sse,/chat/stream); elders wordt dit uitdrukkelijk geweigerd.service_role_key— geheim, RLS omzeilen. Gereserveerd voor de backend.user_jwt— uitgegeven doorPOST /v1/auth/loginna authenticatie. KoptekstAuthorization: Bearer.
# Anonieme klant (gast)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
# Geauthenticeerde client (claimt gebruiker)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
-H "Authorization: Bearer <USER_JWT>"
# Backend (RLS omzeilen)
-H "apikey: <AURABASE_SERVICE_ROLE_KEY>"
-H "Authorization: Bearer <AURABASE_SERVICE_ROLE_KEY>"
Normen toegepast#
Content-Type: application/json— vereist bij POST/PATCH/PUT (behalve uploadopslag, inmultipart/form-data)Prefer: return=representation— retourneert de gemaakte of gewijzigde rijen;return=minimalvoor een antwoord zonder hoofdtekst (204).Prefer: count=exactwordt gelezen op aura-db-mutaties (headersContent-Range+Preference-Applied); Om te vertrouwen op een die leest, gebruikt u de parameter?count=exactRange: 0-49— alleen op een Postgres project bediend door PostgREST, die het zelf interpreteert. Het aura-db-pad (MongoDB-project, of Postgres met PostgREST uitgeschakeld) negeert deze header: het leest alleenlimitenoffset. Geef de voorkeur aanlimit/offset, die op beide motoren werkenIdempotency-Key— wordt NIET gelezen in database (POST /v1/db/…) schrijft: twee identieke POST's creëren twee rijen. Het wordt alleen gehonoreerd doorPOST /v1/notifications/{project_id}/send(en/send/batch) en door het aanmaken van de API-sleutel voor het beheerplan (POST /v1/db/{project_id}/api-keys, 24-uurs venster)
Limiet + offset#
# Enige draagbare vorm - werkt op beide motoren
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?order=id.asc&limit=50&offset=100
# Sleutelset “met de hand”: filter op de laatst gelezen sleutel
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?id=gt.{last_id}&order=id.asc&limit=50
# ?cursor=: ALLEEN aura-db (MongoDB, of Postgres zonder PostgREST).
# Op PostgREST wordt het verzoek geweigerd in 400.
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?cursor={meta.next_cursor}&limit=50
Zonder limit retourneert een leesbewerking maximaal 1000 rijen — dit is zowel de standaard als het harde plafond. Als een query daadwerkelijk meer overeenkomende rijen heeft dan het geretourneerde segment, is meta.has_more true (en false als er geen extra rijen bestaan of het laatste segment is bereikt); vraag om count=exact om ook meta.total te krijgen.
Het totaal wordt niet op dezelfde plaats gelezen, afhankelijk van de engine: op het aura-db-pad draagt het antwoord de header Content-Range: items 100-149/1247 (het totaal is * waard als er geen telling is aangevraagd); op het pad PostgREST geeft de gateway deze header niet door en plaatst het totaal in meta.total van de JSON-envelop. Het tellen gebeurt nooit standaard: vraag dit aan met de parameter ?count=exact (draagbare vorm, vertaald in Prefer door de gateway op het pad PostgREST), ?count=planned of ?count=estimated.
De OpenAPI-beschrijving van uw project wordt weergegeven op GET /v1/db/{project_id}/openapi.json (met uw apikey); het wordt gegenereerd op basis van het liveschema, dus er verschijnt een tabel die u zojuist hebt gemaakt.
Uniform formaat#
error is altijd een object, nooit een string. Er zijn twee varianten, afhankelijk van de uitgever: de velden code en message zijn gemeenschappelijk voor beide, en het is op code (nooit op message, vrije tekst) dat we discrimineren.
{
"error": {
"type": "auth_unauthorized", // machinetype, voorafgegaan door domein
"code": "UNAUTHORIZED", // stabiele code
"message": "Unauthorized: Invalid or revoked API key",
"request_id": "dc20e246-d8e0-412c-b9d7-ce675af6edd5"
}
}
{
"error": {
"code": "COLUMN_NOT_FOUND", // nooit de onbewerkte PGRST-code
"message": "Column unknown_col not found in table sensors",
"details": ""
}
}
PostgREST/PostgreSQL codes (PGRST116, 23505…) worden nooit geretourneerd zoals door de REST API: de gateway vertaalt ze naar 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, anders POSTGREST_ERROR). Deze variant heeft geen type; fouten die door de beller kunnen worden opgelost, voegen een hint toe (een ontbrekende kolom of functie suggereert de dichtstbijzijnde naam, een weigering van RLS geeft de create policy om toe te voegen). De JavaScript SDK bewaart met opzet PGRST116 voor .single() / .maybeSingle(), voor compatibiliteit met supabase-js: op onbewerkte HTTP is dezelfde situatie NOT_SINGULAR.
| Codeer | Naam | Beschrijving |
|---|---|---|
400 | Slecht verzoek | Onjuist opgemaakte payload of query. error.code is BAD_REQUEST. |
401 | Ongeautoriseerd | Ontbrekende of ingetrokken apikey, of ongeldige JWT. error.code is UNAUTHORIZED, of REFRESH_TOKEN_REJECTED op /refresh. |
403 | Verboden | RLS of de autorisatiedienst weigert de bewerking. error.code is FORBIDDEN, QUOTA_EXCEEDED of INSUFFICIENT_PRIVILEGE (pad PostgREST). |
404 | Niet gevonden | De bron bestaat niet of RLS verbergt deze. error.code is NOT_FOUND, RECORD_NOT_FOUND of TABLE_NOT_FOUND. |
406 | Niet acceptabel | Eén rij verwacht, meerdere kwamen terug. error.code is NOT_SINGULAR. |
409 | Conflicten | Unieke of buitenlandse sleutelschending. error.code is CONFLICT, DUPLICATE_KEY of FOREIGN_KEY_VIOLATION. Gebruik on_conflict voor een upsert. |
413 | Laadvermogen te groot | Verzoek groter dan MAX_BODY_SIZE (standaard 50 MB op de gateway). Gebruik een opslagupload met meerdere delen. |
429 | Te veel verzoeken | Tarieflimiet bereikt. error.code is RATE_LIMITED; message noemt de limiet die is bereikt (IP, project of API-sleutel) en hint geeft aan wanneer opnieuw moet worden geprobeerd. X-RateLimit-Limit en X-RateLimit-Remaining headers zijn ingesteld, en Retry-After voor gateway-weigeringen. |
500 | Interne serverfout | Serverfout. Geef error.request_id ter ondersteuning. |
503 | Dienst niet beschikbaar | SERVER_BUSY wanneer de gateway belasting verliest (te veel verzoeken tijdens de vlucht, Retry-After: 1), DB_POOL_TIMEOUT wanneer de verbindingspool van het project verzadigd blijft, de stroomonderbreker open is, een exemplaar ontbreekt of het project in de slaapstand staat (Retry-After: 5 in dat geval). De onderbreker probeert het na 30 seconden opnieuw. |
504 | Gateway-time-out | Time-out stroomopwaarts. error.code is TIMEOUT, of STATEMENT_TIMEOUT wanneer een SQL-instructie langer werd uitgevoerd dan de time-out van de instructie van 10 seconden van het project. |
Via IP bij de gateway, plus limieten per route#
- Per project en API-sleutel: de limiet van het projectplan (Studio › Instellingen › Gebruik). Een
429geeft de getroffen scope aan, zodat u weet of u moet vertragen of upgraden. - Gateway, alle routes: per IP,
100req/s met standaard een burst van1000(aanpasbaar viaRATE_LIMIT_RPS/RATE_LIMIT_BURST). Er is geen aparte laag per rol. - Auth-gevoelig (
login,register,forgot-password,magic-link,email-otp/send,sms/send,refresh,mfa/verify-login): 5 req/min per IP, burst 3. Daarnaast een quotum per project: 30 verbindingen pogingen/uur per IP standaard, instelbaar in de projectinstellingen. Tijdens de ontwikkeling (AURA_ENV=development, de lokale stapel) is de routerlimiet versoepeld (burst 100), zodat u kunt herhalen; de projectquota die worden weergegeven in Studio › Authenticatie › Configuratie › Snelheidslimieten zijn altijd van toepassing. - Ruwe SQL (
/raw): 30 req/min, burst 10. IA: 10 req/min, burst 5.
Overflow → 429 Too Many Requests met de headers X-RateLimit-Limit en X-RateLimit-Remaining (aanwezig bij elk antwoord van de gateway), plus X-RateLimit-Reset en Retry-After bij de weigering.
Volledige boom per dienst#
Elk eindpunt heeft een speciale pagina met parameters, responscodes, voorbeelden in 5 talen en live spoorcode.
DatabaseAuthenticatieOpslagRealtimeFuncties
Er is nog geen SDK voor uw taal#
Er is nog geen Python- of Dart-pakket gepubliceerd (dat zegt de Studio ook). De bovenstaande REST API is compleet, dus een client is een paar regels. De Python-versie gebruikt alleen de standaardbibliotheek; het leest dezelfde variabelen als de andere voorbeelden en verandert een API-fout in een uitzondering die de stabiele code en de request_id draagt:
import json, os, urllib.error, urllib.request
URL = os.environ["NEXT_PUBLIC_AURABASE_URL"]
KEY = os.environ["NEXT_PUBLIC_AURABASE_ANON_KEY"] # of AURABASE_SERVICE_ROLE_KEY op een 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"))
De Dart-versie (Flutter of server) heeft ook geen pakket nodig; voer het uit met 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'));
}