API REST: panoramica
Aurabase superficie HTTP non elaborata. Compatibile con tutte le lingue. URL di base, autenticazione, formato di risposta, codici di errore, quindi dettagli per endpoint in /docs/api/.
Un'origine, il progetto in cammino#
L'URL è il progetto. Ogni progetto viene servito sul proprio sottodominio, https://<slug>.<apex> (localmente http://<slug>.localhost:8080), e il gateway risolve il progetto dall'host: nessun identificatore di progetto viene scritto nei percorsi. Studio › Impostazioni › Connection mostra questo URL e NEXT_PUBLIC_AURABASE_URL lo conserva. Il gateway espone due piani: il piano dati (SDK e applicazioni, :8080 in locale) e il piano di gestione (Studio e amministrazione, :8090). Le superfici del piano dati hanno il prefisso /v1/db, /v1/auth, /v1/storage, /v1/realtime, /v1/functions, /v1/notifications, /v1/ai.
# NEXT_PUBLIC_AURABASE_URL = URL del progetto (es. 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
I moduli che contengono l'UUID del progetto nel percorso (/v1/db/{project_id}/sensors, /v1/auth/{project_id}/login, come nelle pagine di riferimento dell'endpoint) sono ancora accettati nell'URL del progetto e anche nell'origine del gateway nudo. Vengono mantenuti per compatibilità: preferire i moduli sopra, che non dipendono dall'identificatore.
I percorsi di streaming /v1/realtime/ws e /v1/realtime/sse vengono serviti così come sono sull'host del progetto. Un URL che non identifica un progetto (ad esempio l'origine del gateway semplice senza un identificatore di progetto) viene rifiutato come 400.
Due chiavi, una JWT#
anon_key: pubblicabile. Serve come chiave API per qualsiasi richiesta. Intestazioneapikey,X-API-Keyo parametro?apikey=— quest'ultimo è accettato solo su flussi in tempo reale (/ws,/sse,/chat/stream); altrove è esplicitamente rifiutato.service_role_key– segreto, RLS bypass. Riservato al backend.user_jwt: rilasciato daPOST /v1/auth/logindopo l'autenticazione. IntestazioneAuthorization: Bearer.
# Cliente anonimo (ospite)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
# Client autenticato (utente attestazioni)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
-H "Authorization: Bearer <USER_JWT>"
# Backend ( bypass RLS)
-H "apikey: <AURABASE_SERVICE_ROLE_KEY>"
-H "Authorization: Bearer <AURABASE_SERVICE_ROLE_KEY>"
Standard applicati#
Content-Type: application/json: richiesto su POST/PATCH/PUT (eccetto l'archiviazione di caricamento, inmultipart/form-data)Prefer: return=representation— restituisce le righe create o modificate;return=minimalper una risposta senza corpo (204).Prefer: count=exactviene letto sulle mutazioni aura-db (intestazioniContent-Range+Preference-Applied); Per fare affidamento su una lettura , utilizzare il parametro?count=exactRange: 0-49— solo su un progetto Postgres servito da PostgREST, che lo interpreta da solo. Il percorso aura-db (progetto MongoDB o Postgres con PostgREST disabilitato) ignora questa intestazione: legge sololimiteoffset. Preferiscilimit/offset, che funzionano su entrambi i motoriIdempotency-Key— NON viene letto sul database (POST /v1/db/…) scrive: due POST identici creano due righe. È rispettato solo daPOST /v1/notifications/{project_id}/send(e/send/batch) e dalla creazione della chiave API del piano di gestione (POST /v1/db/{project_id}/api-keys, finestra di 24 ore)
Limite + scostamento#
# Solo formato portatile: funziona su entrambi i motori
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?order=id.asc&limit=50&offset=100
# Keyset “a mano”: filtra sull'ultima chiave letta
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?id=gt.{last_id}&order=id.asc&limit=50
# ?cursor=: SOLO aura-db (MongoDB o Postgres senza PostgREST).
# Su PostgREST la richiesta viene rifiutata in 400.
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?cursor={meta.next_cursor}&limit=50
Senza limit, una lettura restituisce al massimo 1000 righe: questo è sia il valore predefinito che il limite massimo. Quando una query ha effettivamente più righe corrispondenti oltre alla sezione restituita, meta.has_more è true (e false quando non esistono righe aggiuntive o è stata raggiunta la sezione finale); chiedi count=exact per ottenere anche meta.total.
Il totale non viene letto nello stesso posto a seconda del motore: sul percorso aura-db, la risposta porta l'intestazione Content-Range: items 100-149/1247 (il totale vale * se non è stato richiesto alcun conteggio); sul percorso PostgREST, il gateway non inoltra questa intestazione e inserisce il totale in meta.total della busta JSON. Il conteggio non viene mai eseguito per impostazione predefinita: richiederlo con il parametro ?count=exact (modulo portatile, tradotto in Prefer dal gateway sul percorso PostgREST), ?count=planned, o ?count=estimated.
La descrizione OpenAPI del tuo progetto è pubblicata su GET /v1/db/{project_id}/openapi.json (con il tuo apikey); viene generato dallo schema live, quindi al suo interno appare una tabella appena creata.
Formato uniforme#
error è sempre un oggetto, mai una stringa. Due varianti, a seconda dell'emittente: i campi code e message sono comuni ad entrambi, ed è su code (mai su message, testo libero) che discriminiamo.
{
"error": {
"type": "auth_unauthorized", // tipo di macchina, preceduto dal dominio
"code": "UNAUTHORIZED", // codice stabile
"message": "Unauthorized: Invalid or revoked API key",
"request_id": "dc20e246-d8e0-412c-b9d7-ce675af6edd5"
}
}
{
"error": {
"code": "COLUMN_NOT_FOUND", // mai il codice PGRST grezzo
"message": "Column unknown_col not found in table sensors",
"details": ""
}
}
I codici PostgREST/PostgreSQL (PGRST116, 23505…) non sono mai restituiti così come sono dall'API REST: il gateway li traduce in codici 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, altrimenti POSTGREST_ERROR). Questa variante non porta type; errori che possono essere corretti dal chiamante aggiungono un hint (una colonna o una funzione mancante suggerisce il nome più vicino, un rifiuto RLS fornisce create policy da aggiungere). L'SDK JavaScript mantiene PGRST116 per .single() / .maybeSingle() di proposito, per compatibilità con supabase-js: su HTTP non elaborato la stessa situazione è NOT_SINGULAR.
| Codice | Nome | Descrizione |
|---|---|---|
400 | Richiesta errata | Payload o query non validi. error.code è BAD_REQUEST. |
401 | Non autorizzato | Mancante o revocato apikey o non valido JWT. error.code è UNAUTHORIZED o REFRESH_TOKEN_REJECTED su /refresh. |
403 | Proibito | RLS o il servizio di autorizzazione rifiuta l'operazione. error.code è FORBIDDEN, QUOTA_EXCEEDED o INSUFFICIENT_PRIVILEGE ( percorso PostgREST). |
404 | Non trovato | La risorsa non esiste o RLS la nasconde. error.code è NOT_FOUND, RECORD_NOT_FOUND o TABLE_NOT_FOUND. |
406 | Non accettabile | Una riga era prevista, diverse tornarono. error.code è NOT_SINGULAR. |
409 | Conflitto | Violazione di chiave univoca o esterna. error.code è CONFLICT, DUPLICATE_KEY o FOREIGN_KEY_VIOLATION. Utilizza on_conflict per un upsert. |
413 | Carico utile troppo grande | Richiesta più grande di MAX_BODY_SIZE (50 MB per impostazione predefinita sul gateway). Utilizza un caricamento di archiviazione in più parti. |
429 | Troppe richieste | Limite di tariffa raggiunto. error.code è RATE_LIMITED; message nomina il limite raggiunto (IP, progetto o chiave API) e hint dice quando riprovare. Vengono impostate le intestazioni X-RateLimit-Limit e X-RateLimit-Remaining e Retry-After sui rifiuti del gateway. |
500 | Errore interno del server | Errore del server. Dai error.request_id al supporto. |
503 | Servizio non disponibile | SERVER_BUSY quando il gateway sta riducendo il carico (troppe richieste in volo, Retry-After: 1), DB_POOL_TIMEOUT quando il pool di connessioni del progetto è rimasto saturo, interruttore aperto, istanza mancante o progetto ibernato (Retry-After: 5 in questo caso). L'interruttore riprova dopo 30 secondi. |
504 | Timeout del gateway | Timeout a monte. error.code è TIMEOUT o STATEMENT_TIMEOUT quando un'istruzione SQL è stata eseguita per un periodo superiore al timeout dell'istruzione di 10 secondi del progetto. |
Tramite IP al gateway, più limiti per percorso#
- Per progetto e chiave API: il limite del piano del progetto (Studio › Impostazioni › Utilizzo). Un
429nomina l'ambito colpito, in modo da sapere se rallentare o aggiornare. - Gateway, tutti i percorsi: per IP,
100req/s con un burst di1000per impostazione predefinita (regolabile tramiteRATE_LIMIT_RPS/RATE_LIMIT_BURST). Non esiste un livello separato per ruolo. - Sensibile all'autenticazione (
login,register,forgot-password,magic-link,email-otp/send,sms/send,refresh,mfa/verify-login): 5 richieste/min per IP, burst 3. Inoltre, a quota per progetto: 30 tentativi di connessione/ora per IP per impostazione predefinita, regolabile nelle impostazioni del progetto. In fase di sviluppo (AURA_ENV=development, lo stack locale), il limite del router è ridotto (burst 100) in modo da poter eseguire l'iterazione; si applicano sempre le quote del progetto visualizzate in Studio › Autenticazione › Configurazione › Limitazione della velocità. - SQL non elaborato (
/raw): 30 richieste/min, burst 10. IA: 10 richieste/min, burst 5.
Overflow → 429 Too Many Requests con le intestazioni X-RateLimit-Limit e X-RateLimit-Remaining (presenti su qualsiasi risposta dal gateway), più X-RateLimit-Reset e Retry-After sul rifiuto.
Albero completo per servizio#
Ogni endpoint ha la sua pagina dedicata con parametri, codici di risposta, esempi in 5 lingue e codice ferroviario in tempo reale.
DatabaseAut.ArchiviazioneTempo realeFunzioni
Nessun SDK ancora per la tua lingua#
Non è ancora stato pubblicato alcun pacchetto Python o Dart (lo dice anche lo Studio). L'API REST sopra è completa, quindi un client dura poche righe. La versione Python utilizza solo la libreria standard; legge le stesse variabili degli altri esempi e trasforma un errore API in un'eccezione che trasporta la scuderia code e request_id:
import json, os, urllib.error, urllib.request
URL = os.environ["NEXT_PUBLIC_AURABASE_URL"]
KEY = os.environ["NEXT_PUBLIC_AURABASE_ANON_KEY"] # o AURABASE_SERVICE_ROLE_KEY su un 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"))
Anche la versione Dart (Flutter o server) non necessita di pacchetto; eseguilo con 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'));
}