İçeriğe geç
Aurabase Logosu
aura tabanı

REST API — Genel Bakış

Aurabase ham HTTP yüzeyi. Tüm dillerle uyumludur. Temel URL, kimlik doğrulama, yanıt biçimi, hata kodları - ardından /docs/api/ dosyasında uç noktaya göre ayrıntılar.

Referans7 dk. okuSeviye referans15 Nis 2026 tarihinde revize edildi

Bu sayfa otomatik olarak çevrildi. İngilizce versiyonu yetkilidir.

Bir başlangıç, proje yolda#

URL'si projenin'sidir. Her proje kendi alt etki alanı olan https://<slug>.<apex> (yerel olarak http://<slug>.localhost:8080) üzerinde sunulur ve ağ geçidi, projeyi ana bilgisayardan çözer: yollara hiçbir proje tanımlayıcı yazılmaz. Studio › Ayarlar › Bağlantı bu URL'yi gösterir ve NEXT_PUBLIC_AURABASE_URL onu tutar. Ağ geçidi iki plan sunar: veri planı (SDK ve uygulamalar, yerel olarak :8080) ve yönetim planı (Stüdyo ve yönetim, :8090). Veri planı yüzeyleri /v1/db, /v1/auth, /v1/storage, /v1/realtime, /v1/functions, /v1/notifications, /v1/ai ön ekidir.

examplesbash
# NEXT_PUBLIC_AURABASE_URL = proje URL'si (ör. 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
Bilgi

Yolda proje UUID'sini taşıyan formlar (/v1/db/{project_id}/sensors, /v1/auth/{project_id}/login, uç nokta referans sayfalarında olduğu gibi) proje URL'sinde ve ayrıca çıplak ağ geçidi kaynağında hala kabul edilmektedir. Uyumluluk amacıyla tutulurlar: tanımlayıcıya bağlı olmayan yukarıdaki formları tercih edin.

Dikkat

/v1/realtime/ws ve /v1/realtime/sse akış rotaları, proje ana bilgisayarında oldukları gibi sunulur. Bir projeyi tanımlamayan bir URL (örneğin, proje tanımlayıcısı olmayan çıplak ağ geçidi kaynağı) 400 olarak reddedilir.

İki anahtar, bir JWT#

  • anon_key — yayınlanabilir. Herhangi bir istek için API anahtarı görevi görür. Başlık apikey, X-API-Key veya parametre ?apikey= — ikincisi yalnızca gerçek zamanlı akışlarda kabul edilir (/ws, /sse, /chat/stream); başka yerlerde açıkça reddedilir.
  • service_role_key — gizli, RLS bypass. Arka uç için ayrılmıştır.
  • user_jwt — kimlik doğrulamasından sonra POST /v1/auth/login tarafından verilir. Başlık Authorization: Bearer.
headers.shbash
# Anonim müşteri (misafir)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"

# Kimliği doğrulanmış istemci (kullanıcıyı talep ediyor)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
-H "Authorization: Bearer <USER_JWT>"

# Arka uç (RLS bypass)
-H "apikey: <AURABASE_SERVICE_ROLE_KEY>"
-H "Authorization: Bearer <AURABASE_SERVICE_ROLE_KEY>"

Uygulanan standartlar#

  • Content-Type: application/json — POST/PATCH/PUT'ta gereklidir (yükleme depolama alanı hariç, multipart/form-data içinde)
  • Prefer: return=representation — oluşturulan veya değiştirilen satırları döndürür; return=minimal gövdesi olmayan bir yanıt için (204). Prefer: count=exact aura-db mutasyonlarında okunur (başlıklar Content-Range + Preference-Applied); okumasına güvenmek için, ?count=exact parametresini kullanın.
  • Range: 0-49 — yalnızca tarafından sunulan ve kendisini yorumlayan PostgREST tarafından sunulan bir Postgres projesinde. Aura-db yolu (MongoDB projesi veya PostgREST devre dışı bırakılmış Postgres) bu başlığını yok sayar: yalnızca limit ve offset okur. Her iki motorda da çalışan limit/offset'yi tercih edin
  • Idempotency-Key — Veritabanında OKUNMAZ (POST /v1/db/…) şunu yazar: iki özdeş POST, iki satır oluşturur. Yalnızca POST /v1/notifications/{project_id}/send (ve /send/batch) ve yönetim planı API anahtarının (POST /v1/db/{project_id}/api-keys, 24 saatlik pencere) oluşturulmasıyla onurlandırılır.

Limit + ofset#

pagination.shbash
# Yalnızca taşınabilir form — her iki motorda da çalışır
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?order=id.asc&limit=50&offset=100

# Tuş takımı "elle": son okunan tuşa göre filtreleme
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?id=gt.{last_id}&order=id.asc&limit=50

# ?cursor=: SADECE aura-db (MongoDB veya Postgres olmadan PostgREST).
# PostgREST tarihinde istek 400'de reddedildi.
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?cursor={meta.next_cursor}&limit=50
İpucu

limit olmadan, bir okuma en fazla 1000 satır döndürür — bu hem varsayılan hem de sabit tavandır. Bir sorguda döndürülen dilimin ötesinde eşleşen daha fazla satır varsa, meta.has_more true olur (ve ek satır olmadığında veya son dilime ulaşıldığında false); count=exact öğesinin ayrıca meta.total almasını isteyin.

Dikkat

Toplam, motora bağlı olarak aynı yerde okunmaz: aura-db yolunda, yanıt Content-Range: items 100-149/1247 başlığını taşır (eğer sayım istenmediyse toplam * değerindedir); PostgREST yolunda, ağ geçidi bu başlığı aktarmaz ve toplamı JSON zarfının meta.total içine yerleştirir. Sayma hiçbir zaman varsayılan olarak yapılmaz: bunu ?count=exact (taşınabilir form, PostgREST yolundaki ağ geçidi tarafından Prefer biçimine çevrilmiş), ?count=planned veya ?count=estimated parametresiyle isteyin.

Projenizin OpenAPI açıklaması GET /v1/db/{project_id}/openapi.json adresinde sunulur (apikey ile birlikte); canlı şemadan oluşturulur, dolayısıyla yeni oluşturduğunuz bir tablo içinde görünür.

Tek tip format#

error her zaman bir nesnedir, asla bir dize değildir. Vericiye bağlı olarak iki değişken vardır - code ve message alanları her ikisinde de ortaktır ve code üzerinde ayrım yaparız (hiçbir zaman message üzerinde, serbest metinde).

Aurabase hizmeti tarafından yayılan hatajson
{
  "error": {
    "type": "auth_unauthorized",      // makine türü, alan adı önekiyle birlikte
    "code": "UNAUTHORIZED",         // kararlı kod
    "message": "Unauthorized: Invalid or revoked API key",
    "request_id": "dc20e246-d8e0-412c-b9d7-ce675af6edd5"
  }
}
Ağ geçidi tarafından çevrilen PostgREST hatasıjson
{
  "error": {
    "code": "COLUMN_NOT_FOUND",    // asla ham PGRST kodunu
    "message": "Column unknown_col not found in table sensors",
    "details": ""
  }
}
Dikkat

PostgREST/PostgreSQL kodları (PGRST116, 23505…) hiçbir zaman REST API tarafından olduğu gibi döndürülmez: ağ geçidi bunları Aurabase kodlarına (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, aksi takdirde POSTGREST_ERROR). Bu değişken type taşımaz; arayan tarafından düzeltilebilecek hatalar bir hint ekler (eksik bir sütun veya işlev en yakın adı önerir, RLS reddi eklenecek create policy değerini verir). JavaScript SDK'sı PGRST116'yi .single() / .maybeSingle() için bilerek tutar, supabase-js ile uyumluluk için: ham HTTP'de aynı durum NOT_SINGULAR.

KodİsimAçıklama
400Kötü İstekHatalı biçimlendirilmiş veri veya sorgu. error.code, BAD_REQUEST'dir.
401YetkisizEksik veya iptal edilmiş apikey ya da geçersiz JWT. error.code, UNAUTHORIZED veya /refresh üzerinde REFRESH_TOKEN_REJECTED'dir.
403YasakRLS veya yetkilendirme servisi işlemi reddediyor. error.code, FORBIDDEN, QUOTA_EXCEEDED veya INSUFFICIENT_PRIVILEGE (PostgREST yolu) şeklindedir.
404BulunamadıKaynak mevcut değil veya RLS onu gizliyor. error.code, NOT_FOUND, RECORD_NOT_FOUND veya TABLE_NOT_FOUND'dir.
406Kabul EdilemezBir satır bekleniyordu, birkaçı geri döndü. error.code, NOT_SINGULAR'dir.
409ÇatışmaBenzersiz veya yabancı anahtar ihlali. error.code, CONFLICT, DUPLICATE_KEY veya FOREIGN_KEY_VIOLATION'dir. Yükseliş için on_conflict kullanın.
413Yük Çok BüyükMAX_BODY_SIZE değerinden büyük istek (ağ geçidinde varsayılan olarak 50 MB). Çok parçalı bir depolama yüklemesi kullanın.
429Çok Fazla İstekOran sınırına ulaşıldı. error.code RATE_LIMITED'dir; message ulaşılan sınırı (IP, proje veya API anahtarı) belirtir ve hint ne zaman yeniden deneneceğini söyler. X-RateLimit-Limit ve X-RateLimit-Remaining başlıkları ayarlandı ve ağ geçidi retlerinde Retry-After.
500Dahili Sunucu HatasıSunucu hatası. Desteğe error.request_id verin.
503Hizmet Mevcut DeğilSERVER_BUSY ağ geçidi yükü boşaltırken (uçuş sırasında çok fazla istek, Retry-After: 1), DB_POOL_TIMEOUT projenin bağlantı havuzu doymuş kaldığında, devre kesici açık olduğunda, örnek eksik olduğunda veya proje hazırda beklettiğinde (bu durumda Retry-After: 5). Kesici 30 saniye sonra yeniden dener.
504Ağ Geçidi Zaman AşımıYukarı akış zaman aşımı. error.code, TIMEOUT veya bir SQL ifadesi projenin 10 saniyelik ifade zaman aşımından daha uzun çalıştığında STATEMENT_TIMEOUT olur.

Ağ geçidindeki IP'ye ve rota başına limitlere göre#

  • Proje ve API anahtarı başına: proje planının sınırı (Studio › Ayarlar › Kullanım). Bir 429 vurulan kapsamı adlandırır, böylece yavaşlamanız mı yoksa yükseltmeniz mi gerektiğini bilirsiniz.
  • Ağ geçidi, tüm yollar: IP başına, varsayılan olarak 1000 patlamasıyla 100 istek/sn (RATE_LIMIT_RPS / RATE_LIMIT_BURST aracılığıyla ayarlanabilir). Rol başına ayrı bir katman yoktur.
  • Kimlik doğrulamasına duyarlı (login, register, forgot-password, magic-link, email-otp/send, sms/send, refresh, mfa/verify-login): IP başına 5 istek/dakika, seri çekim 3. Ek olarak, bir proje başına kota: Varsayılan olarak IP başına 30 bağlantı denemesi/saat, proje ayarlarından ayarlanabilir. Geliştirme aşamasında (AURA_ENV=development, yerel yığın), yönlendirici sınırı gevşetilmiştir (artık 100), böylece yineleyebilirsiniz; Studio › Kimlik Doğrulama › Yapılandırma › Hız sınırlama bölümünde gösterilen proje kotaları her zaman geçerlidir.
  • Ham SQL (/raw): 30 istek/dak, patlama 10. IA: 10 istek/dak, patlama 5.
Dikkat

Taşma → X-RateLimit-Limit ve X-RateLimit-Remaining (ağ geçidinden gelen herhangi bir yanıtta mevcut) başlıklarıyla birlikte 429 Too Many Requests, ayrıca reddetme durumunda X-RateLimit-Reset ve Retry-After.

Hizmet başına ağacı tamamla#

Her uç noktanın parametreleri, yanıt kodlarını, 5 dilde örnekleri ve canlı demiryolu kodunu içeren özel sayfası vardır.

VeritabanıKimlik DoğrulamasıDepolamaGerçek Zamanlıİşlevler

Diliniz için henüz SDK yok#

Henüz yayınlanmış bir Python veya Dart paketi yok (Stüdyo da öyle söylüyor). Yukarıdaki REST API tamamlandı, dolayısıyla istemci birkaç satırdan oluşuyor. Python sürümü yalnızca standart kitaplığı kullanır; diğer örneklerle aynı değişkenleri okur ve bir API hatasını, kararlı code ve request_id öğelerini taşıyan bir istisnaya dönüştürür:

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"]  # veya bir sunucuda AURABASE_SERVICE_ROLE_KEY


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

Dart sürümünün (Flutter veya sunucu) da pakete ihtiyacı yoktur; dart run aurabase_rest.dart ile çalıştırın:

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

Daha ileri gitmek için#