Vai al contenuto
Logo Aurabase
aurabase

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

Riferimento7 min lettoLivello riferimentoRevisionato il 15 apr 2026

Questa pagina è stata tradotta automaticamente. Fa fede la versione inglese.

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.

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

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.

Attenzione

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. Intestazione apikey, X-API-Key o 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 da POST /v1/auth/login dopo l'autenticazione. Intestazione Authorization: Bearer.
headers.shbash
# 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, in multipart/form-data)
  • Prefer: return=representation — restituisce le righe create o modificate; return=minimal per una risposta senza corpo (204). Prefer: count=exact viene letto sulle mutazioni aura-db (intestazioni Content-Range + Preference-Applied); Per fare affidamento su una lettura , utilizzare il parametro ?count=exact
  • Range: 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 solo limit e offset. Preferisci limit/offset, che funzionano su entrambi i motori
  • Idempotency-Key — NON viene letto sul database (POST /v1/db/…) scrive: due POST identici creano due righe. È rispettato solo da POST /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#

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

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.

Attenzione

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.

errore emesso da un servizio Aurabasejson
{
  "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"
  }
}
Errore PostgREST tradotto dal gatewayjson
{
  "error": {
    "code": "COLUMN_NOT_FOUND",    // mai il codice PGRST grezzo
    "message": "Column unknown_col not found in table sensors",
    "details": ""
  }
}
Attenzione

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.

CodiceNomeDescrizione
400Richiesta errataPayload o query non validi. error.code è BAD_REQUEST.
401Non autorizzatoMancante o revocato apikey o non valido JWT. error.code è UNAUTHORIZED o REFRESH_TOKEN_REJECTED su /refresh.
403ProibitoRLS o il servizio di autorizzazione rifiuta l'operazione. error.code è FORBIDDEN, QUOTA_EXCEEDED o INSUFFICIENT_PRIVILEGE ( percorso PostgREST).
404Non trovatoLa risorsa non esiste o RLS la nasconde. error.code è NOT_FOUND, RECORD_NOT_FOUND o TABLE_NOT_FOUND.
406Non accettabileUna riga era prevista, diverse tornarono. error.code è NOT_SINGULAR.
409ConflittoViolazione di chiave univoca o esterna. error.code è CONFLICT, DUPLICATE_KEY o FOREIGN_KEY_VIOLATION. Utilizza on_conflict per un upsert.
413Carico utile troppo grandeRichiesta più grande di MAX_BODY_SIZE (50 MB per impostazione predefinita sul gateway). Utilizza un caricamento di archiviazione in più parti.
429Troppe richiesteLimite 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.
500Errore interno del serverErrore del server. Dai error.request_id al supporto.
503Servizio non disponibileSERVER_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.
504Timeout del gatewayTimeout 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 429 nomina l'ambito colpito, in modo da sapere se rallentare o aggiornare.
  • Gateway, tutti i percorsi: per IP, 100 req/s con un burst di 1000 per impostazione predefinita (regolabile tramite RATE_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.
Attenzione

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:

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

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

Per andare oltre#