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.
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.
# 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
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.
/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ıkapikey,X-API-Keyveya 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 sonraPOST /v1/auth/logintarafından verilir. BaşlıkAuthorization: Bearer.
# 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-dataiçinde)Prefer: return=representation— oluşturulan veya değiştirilen satırları döndürür;return=minimalgövdesi olmayan bir yanıt için (204).Prefer: count=exactaura-db mutasyonlarında okunur (başlıklarContent-Range+Preference-Applied); okumasına güvenmek için,?count=exactparametresini 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ızcalimitveoffsetokur. Her iki motorda da çalışanlimit/offset'yi tercih edinIdempotency-Key— Veritabanında OKUNMAZ (POST /v1/db/…) şunu yazar: iki özdeş POST, iki satır oluşturur. YalnızcaPOST /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#
# 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
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.
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).
{
"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"
}
}
{
"error": {
"code": "COLUMN_NOT_FOUND", // asla ham PGRST kodunu
"message": "Column unknown_col not found in table sensors",
"details": ""
}
}
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 | İsim | Açıklama |
|---|---|---|
400 | Kötü İstek | Hatalı biçimlendirilmiş veri veya sorgu. error.code, BAD_REQUEST'dir. |
401 | Yetkisiz | Eksik veya iptal edilmiş apikey ya da geçersiz JWT. error.code, UNAUTHORIZED veya /refresh üzerinde REFRESH_TOKEN_REJECTED'dir. |
403 | Yasak | RLS veya yetkilendirme servisi işlemi reddediyor. error.code, FORBIDDEN, QUOTA_EXCEEDED veya INSUFFICIENT_PRIVILEGE (PostgREST yolu) şeklindedir. |
404 | Bulunamadı | Kaynak mevcut değil veya RLS onu gizliyor. error.code, NOT_FOUND, RECORD_NOT_FOUND veya TABLE_NOT_FOUND'dir. |
406 | Kabul Edilemez | Bir satır bekleniyordu, birkaçı geri döndü. error.code, NOT_SINGULAR'dir. |
409 | Çatışma | Benzersiz veya yabancı anahtar ihlali. error.code, CONFLICT, DUPLICATE_KEY veya FOREIGN_KEY_VIOLATION'dir. Yükseliş için on_conflict kullanın. |
413 | Yük Çok Büyük | MAX_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 İstek | Oran 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. |
500 | Dahili Sunucu Hatası | Sunucu hatası. Desteğe error.request_id verin. |
503 | Hizmet Mevcut Değil | SERVER_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. |
504 | Ağ 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
429vurulan 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
1000patlamasıyla100istek/sn (RATE_LIMIT_RPS/RATE_LIMIT_BURSTaracı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.
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:
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:
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'));
}