रेस्ट एपीआई - अवलोकन
Aurabase कच्ची HTTP सतह। सभी भाषाओं के साथ संगत. आधार यूआरएल, प्रमाणीकरण, प्रतिक्रिया प्रारूप, त्रुटि कोड - फिर /docs/api/ में समापन बिंदु द्वारा विवरण।
एक उत्पत्ति, रास्ते में परियोजना#
यूआरएल प्रोजेक्ट है। प्रत्येक प्रोजेक्ट को उसके अपने उप-डोमेन, https://<slug>.<apex> (स्थानीय रूप से http://<slug>.localhost:8080) पर परोसा जाता है, और गेटवे होस्ट से प्रोजेक्ट को हल करता है: पथों में कोई प्रोजेक्ट पहचानकर्ता नहीं लिखा गया है। स्टूडियो › सेटिंग्स › कनेक्शन इस यूआरएल को दिखाता है, और NEXT_PUBLIC_AURABASE_URL इसे रखता है। गेटवे दो योजनाओं को उजागर करता है: डेटा योजना (एसडीके और एप्लिकेशन, :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
प्रोजेक्ट यूयूआईडी को पथ में ले जाने वाले फॉर्म (/v1/db/{project_id}/sensors, /v1/auth/{project_id}/login, जैसा कि एंडपॉइंट संदर्भ पृष्ठों में है) अभी भी प्रोजेक्ट यूआरएल पर और नंगे गेटवे मूल पर भी स्वीकार किए जाते हैं। उन्हें अनुकूलता के लिए रखा जाता है: ऊपर दिए गए फॉर्म को प्राथमिकता दें, जो पहचानकर्ता पर निर्भर नहीं होते हैं।
स्ट्रीमिंग रूट /v1/realtime/ws और /v1/realtime/sse को वैसे ही परोसा जाता है जैसे वे प्रोजेक्ट होस्ट पर हैं। एक यूआरएल जो किसी प्रोजेक्ट की पहचान नहीं करता है (उदाहरण के लिए प्रोजेक्ट पहचानकर्ता के बिना नंगे गेटवे मूल) को 400 के रूप में खारिज कर दिया जाता है।
दो चाबियाँ, एक JWT#
anon_key- प्रकाशन योग्य। किसी भी अनुरोध के लिए एपीआई कुंजी के रूप में कार्य करता है। हेडर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को ऑरा-डीबी म्यूटेशन (हेडरContent-Range+Preference-Applied) पर पढ़ा जाता है; रीडिंग पर भरोसा करने के लिए,?count=exactपैरामीटर का उपयोग करेंRange: 0-49- केवल Postgres प्रोजेक्ट पर PostgREST द्वारा परोसा जाता है, जो स्वयं इसकी व्याख्या करता है। ऑरा-डीबी पथ (MongoDB प्रोजेक्ट, या Postgres PostgREST अक्षम के साथ) इस हेडर को अनदेखा करता है: यह केवलlimitऔरoffsetपढ़ता है।limit/offsetको प्राथमिकता दें, जो दोनों इंजनों पर काम करते हैंIdempotency-Key- डेटाबेस पर नहीं पढ़ा जाता है (POST /v1/db/…) लिखता है: दो समान POSTs दो पंक्तियाँ बनाते हैं। इसे केवलPOST /v1/notifications/{project_id}/send(और/send/batch), और प्रबंधन योजना एपीआई कुंजी (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
# ?कर्सर=: केवल आभा-डीबी (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 जब कोई अतिरिक्त पंक्तियाँ मौजूद नहीं होती हैं या अंतिम स्लाइस तक पहुँच चुका होता है); meta.total पाने के लिए count=exact मांगें।
इंजन के आधार पर कुल को एक ही स्थान पर नहीं पढ़ा जाता है: आभा-डीबी पथ पर, प्रतिक्रिया में हेडर Content-Range: items 100-149/1247 होता है (यदि कोई गिनती का अनुरोध नहीं किया गया था तो कुल * के लायक है); PostgREST पथ पर, गेटवे इस हेडर को रिले नहीं करता है और कुल को JSON लिफाफे के meta.total में रखता है। गणना कभी भी डिफ़ॉल्ट रूप से नहीं की जाती है: इसे पैरामीटर ?count=exact (पोर्टेबल फॉर्म, PostgREST पथ पर गेटवे द्वारा Prefer में अनुवादित), ?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", // कच्चा पीजीआरएसटी कोड कभी नहीं
"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 देता है)। जावास्क्रिप्ट SDK उद्देश्य के लिए .single() / .maybeSingle() के लिए PGRST116 रखता है, supabase-js के साथ संगतता के लिए: कच्चे HTTP पर वही स्थिति NOT_SINGULAR है।
| कोड | नाम | विवरण |
|---|---|---|
400 | खराब अनुरोध | विकृत पेलोड या क्वेरी. error.code BAD_REQUEST है। |
401 | अनधिकृत | गुम या निरस्त apikey, या अमान्य JWT. error.code UNAUTHORIZED है, या /refresh पर REFRESH_TOKEN_REJECTED है। |
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 उस सीमा को बताता है जो हिट हुई थी (आईपी, प्रोजेक्ट या एपीआई कुंजी) और 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-सेकंड स्टेटमेंट टाइमआउट से अधिक समय तक चलता है। |
गेटवे पर आईपी द्वारा, प्रति मार्ग प्लस सीमाएँ#
- प्रति प्रोजेक्ट और एपीआई कुंजी: प्रोजेक्ट की योजना की सीमा (स्टूडियो › सेटिंग्स › उपयोग)।
429उस स्कोप को नाम देता है जो हिट हुआ था, ताकि आप जान सकें कि धीमा करना है या अपग्रेड करना है। - गेटवे, सभी मार्ग: प्रति आईपी,
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 रेक/मिनट, बर्स्ट 3. इसके अलावा, प्रति प्रोजेक्ट एक कोटा: 30 कनेक्शन प्रयास/घंटा प्रति आईपी डिफ़ॉल्ट रूप से, प्रोजेक्ट सेटिंग्स में समायोज्य। विकास में (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।
प्रति सेवा पूर्ण वृक्ष#
प्रत्येक समापन बिंदु का अपना समर्पित पृष्ठ होता है जिसमें पैरामीटर, प्रतिक्रिया कोड, 5 भाषाओं में उदाहरण और लाइव रेल कोड होता है।
डेटाबेसप्रामाणिकसंग्रहणरीयलटाइमफ़ंक्शन
आपकी भाषा के लिए अभी तक कोई SDK नहीं है#
अभी तक कोई प्रकाशित पायथन या डार्ट पैकेज नहीं है (स्टूडियो भी ऐसा कहता है)। उपरोक्त REST 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 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'));
}