واجهة برمجة تطبيقات REST — نظرة عامة
Aurabase سطح HTTP الخام. متوافق مع جميع اللغات. عنوان URL الأساسي، والمصادقة، وتنسيق الاستجابة، ورموز الخطأ - ثم التفاصيل حسب نقطة النهاية في /docs/api/.
أصل، المشروع في الطريق#
عنوان URL هو المشروع. يتم تقديم كل مشروع في المجال الفرعي الخاص به، https://<slug>.<apex> (محليًا http://<slug>.localhost:8080)، وتقوم البوابة بحل المشروع من المضيف: لا تتم كتابة معرف المشروع في المسارات. يعرض الاستوديو › الإعدادات › الاتصال عنوان URL هذا، ويحتفظ به NEXT_PUBLIC_AURABASE_URL. تعرض البوابة خطتين: خطة البيانات (SDK والتطبيقات، :8080 محليًا) وخطة الإدارة (الاستوديو والإدارة، :8090). أسطح خطة البيانات مسبوقة بـ /v1/db, /v1/auth, /v1/storage, /v1/realtime, /v1/functions, /v1/notifications, /v1/ai.
# NEXT_PUBLIC_AURABASE_URL = عنوان URL للمشروع (على سبيل المثال، 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
لا تزال النماذج التي تحمل UUID الخاص بالمشروع في المسار (/v1/db/{project_id}/sensors، /v1/auth/{project_id}/login، كما هو الحال في الصفحات المرجعية لنقطة النهاية) مقبولة على عنوان URL للمشروع، وكذلك على أصل البوابة العارية. يتم الاحتفاظ بها من أجل التوافق: تفضل النماذج المذكورة أعلاه، والتي لا تعتمد على المعرف.
يتم تقديم مسارات البث /v1/realtime/ws و/v1/realtime/sse كما هي على مضيف المشروع. يتم رفض عنوان URL الذي لا يحدد مشروعًا (على سبيل المثال أصل البوابة العارية بدون معرف المشروع) باعتباره 400.
مفتاحين، واحد JWT#
anon_key— قابل للنشر. بمثابة مفتاح API لأي طلب. الرأسapikeyأوX-API-Keyأو المعلمة?apikey=- يتم قبول الأخير فقط في التدفقات في الوقت الفعلي (/ws,/sse,/chat/stream); في مكان آخر تم رفضه صراحة.service_role_key- سر، RLS تجاوز. محفوظة للخلفية.user_jwt- تم إصداره بواسطةPOST /v1/auth/loginبعد المصادقة. رأسAuthorization: Bearer.
# العميل المجهول (ضيف)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
# العميل الذي تمت مصادقته (مستخدم المطالبات)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
-H "Authorization: Bearer <USER_JWT>"
# الواجهة الخلفية (تجاوز RLS)
-H "apikey: <AURABASE_SERVICE_ROLE_KEY>"
-H "Authorization: Bearer <AURABASE_SERVICE_ROLE_KEY>"
المعايير المطبقة#
Content-Type: application/json— مطلوب في POST/PATCH/PUT (باستثناء تخزين التحميل، فيmultipart/form-data)Prefer: return=representation— يُرجع الصفوف التي تم إنشاؤها أو تعديلها؛return=minimalللرد بلا جسم (204). تتم قراءةPrefer: count=exactعلى طفرات aura-db (الرؤوسContent-Range+Preference-Applied)؛ للاعتماد على قراءة ، استخدم المعلمة?count=exactRange: 0-49— فقط في مشروع Postgres يخدمه PostgREST والذي يفسره بنفسه. مسار aura-db (مشروع MongoDB، أو Postgres مع تعطيل PostgREST) يتجاهل هذا الرأس: يقرأ فقطlimitوoffset. تفضلlimit/offsetوالتي تعمل على كلا المحركينIdempotency-Key— لا تتم قراءته في قاعدة البيانات (POST /v1/db/…) يكتب: تنشئ مشاركتان متطابقتان صفين. يتم تكريمه فقط بواسطةPOST /v1/notifications/{project_id}/send(و/send/batch)، ومن خلال إنشاء مفتاح API لخطة الإدارة (POST /v1/db/{project_id}/api-keys، نافذة 24 ساعة)
الحد + الإزاحة#
# النموذج المحمول الوحيد هو أنه يعمل على كلا المحركين
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?order=id.asc&limit=50&offset=100
# مجموعة المفاتيح "باليد": تصفية على آخر مفتاح تمت قراءته
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?id=gt.{last_id}&order=id.asc&limit=50
# ?cursor=: aura-db فقط (MongoDB، أو Postgres بدون PostgREST).
# في PostgREST تم رفض الطلب في 400.
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?cursor={meta.next_cursor}&limit=50
بدون limit، ترجع القراءة على الأكثر 1000 صف - وهذا هو السقف الافتراضي والسقف الثابت. عندما يحتوي الاستعلام بالفعل على المزيد من الصفوف المتطابقة خارج الشريحة التي تم إرجاعها، فإن meta.has_more يكون true (و false عند عدم وجود صفوف إضافية أو عند الوصول إلى الشريحة النهائية)؛ اطلب count=exact لتحصل أيضًا على meta.total.
لا تتم قراءة الإجمالي في نفس المكان اعتمادًا على المحرك: على مسار aura-db، تحمل الاستجابة الرأس Content-Range: items 100-149/1247 (يبلغ الإجمالي * إذا لم يتم طلب أي حساب)؛ على المسار PostgREST، لا تقوم البوابة بترحيل هذا الرأس وتضع الإجمالي في meta.total لمغلف JSON. لا يتم إجراء العد افتراضيًا أبدًا: اطلبه باستخدام المعلمة ?count=exact (نموذج محمول، تمت ترجمته إلى Prefer بواسطة البوابة الموجودة على المسار PostgREST) أو ?count=planned أو ?count=estimated.
يتم تقديم وصف OpenAPI لمشروعك على GET /v1/db/{project_id}/openapi.json (مع apikey)؛ يتم إنشاؤه من المخطط المباشر، لذلك يظهر فيه الجدول الذي قمت بإنشائه للتو.
تنسيق موحد#
error هو دائمًا كائن، وليس سلسلة. هناك متغيران، اعتمادًا على جهة الإصدار - الحقول code وmessage مشتركة في كليهما، ونحن نميز في code (أبدًا في message، النص الحر).
{
"error": {
"type": "auth_unauthorized", // نوع الجهاز، مسبوقًا بالمجال
"code": "UNAUTHORIZED", // رمز مستقر
"message": "Unauthorized: Invalid or revoked API key",
"request_id": "dc20e246-d8e0-412c-b9d7-ce675af6edd5"
}
}
{
"error": {
"code": "COLUMN_NOT_FOUND", // أبدا رمز PGRST الخام
"message": "Column unknown_col not found in table sensors",
"details": ""
}
}
رموز PostgREST/PostgreSQL (PGRST116, 23505...) لا يتم إرجاع أبدًا كما هي بواسطة REST API: تترجمها البوابة إلى رموز 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, وإلا POSTGREST_ERROR). هذا المتغير لا يحمل type؛ الأخطاء التي يمكن إصلاحها بواسطة المتصل تضيف hint (يقترح العمود أو الوظيفة المفقودة أقرب اسم، ويؤدي رفض RLS إلى إضافة create policy). يحتفظ JavaScript SDK بـ PGRST116 لـ .single() / .maybeSingle() عن قصد، من أجل التوافق مع supabase-js: على HTTP الخام نفس الموقف هو NOT_SINGULAR.
| الكود | الاسم | الوصف |
|---|---|---|
400 | طلب سيء | حمولة أو استعلام غير صحيح. error.code هو BAD_REQUEST. |
401 | غير مصرح به | مفقود أو تم إبطاله apikey أو غير صالح JWT. error.code هو UNAUTHORIZED أو REFRESH_TOKEN_REJECTED على /refresh. |
403 | ممنوع | RLS أو أن خدمة التفويض ترفض العملية. error.code هو FORBIDDEN أو QUOTA_EXCEEDED أو INSUFFICIENT_PRIVILEGE (مسار PostgREST). |
404 | لم يتم العثور عليه | المورد غير موجود أو أن RLS يخفيه. error.code هو NOT_FOUND أو RECORD_NOT_FOUND أو TABLE_NOT_FOUND. |
406 | غير مقبول | كان من المتوقع وجود صف واحد، وعاد العديد منهم. error.code هو NOT_SINGULAR. |
409 | الصراع | انتهاك المفتاح الفريد أو الخارجي. error.code هو CONFLICT أو DUPLICATE_KEY أو FOREIGN_KEY_VIOLATION. استخدم on_conflict للإزعاج. |
413 | الحمولة كبيرة جدًا | طلب أكبر من MAX_BODY_SIZE (50 ميجابايت بشكل افتراضي على البوابة). استخدم تحميل تخزين متعدد الأجزاء. |
429 | طلبات كثيرة جدًا | تم الوصول إلى الحد الأقصى للسعر. error.code هو RATE_LIMITED؛ message يسمي الحد الذي تم الوصول إليه (IP أو مشروع أو مفتاح API) ويحدد hint متى يجب إعادة المحاولة. تم تعيين رؤوس X-RateLimit-Limit وX-RateLimit-Remaining، وRetry-After عند رفض البوابة. |
500 | خطأ داخلي في الخادم | خطأ في الخادم. أعط error.request_id للدعم. |
503 | الخدمة غير متوفرة | SERVER_BUSY عندما تتخلص البوابة من الحمل (عدد كبير جدًا من الطلبات أثناء الطيران، Retry-After: 1)، DB_POOL_TIMEOUT عندما يظل تجمع اتصال المشروع مشبعًا، أو يكون قاطع الدائرة مفتوحًا، أو يكون المثيل مفقودًا، أو يكون المشروع في حالة سبات (Retry-After: 5 في هذه الحالة). يقوم القاطع بإعادة المحاولة بعد 30 ثانية. |
504 | مهلة البوابة | مهلة المنبع. error.code هو TIMEOUT أو STATEMENT_TIMEOUT عندما يتم تشغيل عبارة SQL لفترة أطول من مهلة بيان المشروع البالغة 10 ثوانٍ. |
عن طريق IP عند البوابة، بالإضافة إلى الحدود لكل مسار#
- لكل مشروع ومفتاح API: الحد الأقصى لخطة المشروع (الاستوديو › الإعدادات › الاستخدام). يقوم
429بتسمية النطاق الذي تم الوصول إليه، حتى تعرف ما إذا كنت تريد إبطاء السرعة أو الترقية. - البوابة، جميع المسارات: لكل IP،
100req/s مع سلسلة من1000بشكل افتراضي (قابل للتعديل عبرRATE_LIMIT_RPS/RATE_LIMIT_BURST). لا يوجد مستوى منفصل لكل دور. - حساس للمصادقة (
login,register,forgot-password,magic-link,email-otp/send,sms/send,refresh,mfa/verify-login): 5 req/min لكل IP، متتابع 3. بالإضافة إلى ذلك، أ الحصة لكل مشروع: 30 محاولة اتصال/ساعة لكل IP بشكل افتراضي، قابلة للتعديل في إعدادات المشروع. في التطوير (AURA_ENV=development، المكدس المحلي)، تم تخفيف حد جهاز التوجيه (اندفاع 100) حتى تتمكن من التكرار؛ حصص المشروع الموضحة في الاستوديو › المصادقة › التكوين › تنطبق دائمًا حدود المعدل. - SQL الخام (
/raw): 30 طلب/دقيقة، انفجار 10. IA: 10 طلب/دقيقة، انفجار 5.
التجاوز → 429 Too Many Requests مع الرؤوس X-RateLimit-Limit وX-RateLimit-Remaining (موجود في أي استجابة من البوابة)، بالإضافة إلى X-RateLimit-Reset وRetry-After في حالة الرفض.
شجرة كاملة لكل خدمة#
تحتوي كل نقطة نهاية على صفحتها المخصصة التي تحتوي على المعلمات ورموز الاستجابة والأمثلة بخمس لغات ورمز السكك الحديدية المباشر.
قاعدة البياناتالمصادقةالتخزينالوقت الحقيقيالوظائف
لا يوجد SDK للغتك حتى الآن#
لا توجد حزمة Python أو Dart منشورة حتى الآن (يقول الاستوديو ذلك أيضًا). اكتملت واجهة REST API المذكورة أعلاه، لذا فإن العميل يتكون من بضعة أسطر. يستخدم إصدار بايثون المكتبة القياسية فقط؛ يقرأ نفس المتغيرات مثل الأمثلة الأخرى ويحول خطأ API إلى استثناء يحمل الثابت code وrequest_id:
import json, os, urllib.error, urllib.request
URL = os.environ["NEXT_PUBLIC_AURABASE_URL"]
KEY = os.environ["NEXT_PUBLIC_AURABASE_ANON_KEY"] # أو 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 (Flutter أو الخادم) لا يحتاج إلى حزمة أيضًا؛ قم بتشغيله باستخدام 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'));
}