본문으로 건너뛰기
아우라베이스 로고
아우라베이스

REST API — 개요

Aurabase 원시 HTTP 표면. 모든 언어와 호환됩니다. 기본 URL, 인증, 응답 형식, 오류 코드 — 그런 다음 /docs/api/의 엔드포인트별 세부정보입니다.

레퍼런스7분 읽기레벨 참조2026. 4. 15.에 개정됨

이 페이지는 자동으로 번역되었습니다. 영어 버전은 권위가 있습니다.

원점, 진행 중인 프로젝트#

URL은 프로젝트입니다. 각 프로젝트는 자체 하위 도메인인 https://<slug>.<apex>(로컬에서는 http://<slug>.localhost:8080)에서 제공되며 게이트웨이는 호스트에서 프로젝트를 확인합니다. 경로에 프로젝트 식별자가 기록되지 않습니다. Studio › 설정 › Connection은 이 URL을 표시하고 NEXT_PUBLIC_AURABASE_URL는 이를 보유합니다. 게이트웨이는 데이터 계획(SDK 및 애플리케이션, 로컬로 :8080)과 관리 계획(Studio 및 관리, :8090)이라는 두 가지 계획을 공개합니다. 데이터 계획 표면에는 /v1/db, /v1/auth, /v1/storage, /v1/realtime, /v1/functions, /v1/notifications, /v1/ai접두사가 붙습니다.

examplesbash
# 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.
headers.shbash
# 익명의 고객(게스트)
-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=exact 매개변수를 사용하세요.
  • Range: 0-49 — 자체적으로 해석하는 PostgREST에서 제공하는 Postgres 프로젝트에서만 가능합니다. aura-db 경로(MongoDB 프로젝트 또는 PostgREST가 비활성화된 Postgres)는 이 헤더를 무시합니다. 즉, limit 및 offset만 읽습니다. 두 엔진 모두에서 작동하는 limit/offset선호
  • Idempotency-Key — 는 데이터베이스에서 읽히지 않습니다.(POST /v1/db/…) 쓰기: 두 개의 동일한 POST가 두 개의 행을 생성합니다. 이는 POST /v1/notifications/{project_id}/send(및 /send/batch) 및 관리 계획 API 키 생성(POST /v1/db/{project_id}/api-keys, 24시간 창)에 의해서만 적용됩니다.

한계 + 오프셋#

pagination.shbash
# 휴대용 형식으로만 — 두 엔진 모두에서 작동
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 또는 PostgREST없는 Postgres).
# 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를 요청하세요.

주의

총계는 엔진에 따라 동일한 위치에서 읽혀지지 않습니다. aura-db 경로에서 응답은 헤더 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, 자유 텍스트에는 없음)입니다.

Aurabase 서비스에서 발생한 오류json
{
  "error": {
    "type": "auth_unauthorized",      // 도메인이 앞에 붙는 머신 유형
    "code": "UNAUTHORIZED",         // 안정적인 코드
    "message": "Unauthorized: Invalid or revoked API key",
    "request_id": "dc20e246-d8e0-412c-b9d7-ce675af6edd5"
  }
}
PostgREST 오류가 게이트웨이에 의해 번역되었습니다.json
{
  "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는 supabase-js와의 호환성을 위해 의도적으로 .single() / .maybeSingle()에 대해 PGRST116를 유지합니다. 원시 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입니다. Upsert에는 on_conflict를 사용하세요.
413페이로드가 너무 큼MAX_BODY_SIZE(게이트웨이에서 기본적으로 50MB)보다 큰 요청입니다. 멀티파트 스토리지 업로드를 사용하세요.
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또는 SQL 문이 프로젝트의 10초 문 제한 시간보다 오래 실행된 경우 STATEMENT_TIMEOUT입니다.

게이트웨이의 IP 및 경로당 한도 기준#

  • 프로젝트 및 API 키별: 프로젝트 계획의 한도(Studio › 설정 › 사용량). 429는 적중된 범위의 이름을 지정하므로 속도를 늦출지 업그레이드할지 알 수 있습니다.
  • 게이트웨이, 모든 경로: IP당, 기본적으로 버스트가 1000인 100 요청/초(RATE_LIMIT_RPS / RATE_LIMIT_BURST를 통해 조정 가능). 역할별로 별도의 계층이 없습니다.
  • 인증에 민감한 (login, register, forgot-password, magic-link, email-otp/send, sms/send, refresh, mfa/verify-login): IP당 요청/분 5개, 버스트 3. 또한, 프로젝트당 할당량: 기본적으로 IP당 시간당 30번의 연결 시도, 프로젝트 설정에서 조정 가능. 개발(AURA_ENV=development, 로컬 스택)에서는 라우터 제한이 완화되어(100 버스트) 반복할 수 있습니다. Studio › 인증 › 구성 › 속도 제한에 표시된 프로젝트 할당량은 항상 적용됩니다.
  • 원시 SQL (/raw): 30 요청/분, 버스트 10. IA: 10 요청/분, 버스트 5.
주의

오버플로 → 헤더 X-RateLimit-Limit 및 X-RateLimit-Remaining(게이트웨이의 모든 응답에 있음)가 있는 429 Too Many Requests, 거부 시 X-RateLimit-Reset 및 Retry-After.

서비스당 완전한 트리#

각 엔드포인트에는 매개변수, 응답 코드, 5개 언어로 된 예시 및 실시간 철도 코드가 포함된 전용 페이지가 있습니다.

데이터베이스인증스토리지실시간함수

귀하의 언어에는 아직 SDK가 없습니다.#

아직 게시된 Python 또는 Dart 패키지가 없습니다(Studio에서도 그렇게 말합니다). 위의 REST API는 완성되었으므로 클라이언트는 몇 줄이면 됩니다. Python 버전은 표준 라이브러리만 사용합니다. 다른 예제와 동일한 변수를 읽고 API 오류를 안정적인 code 및 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"]  # 또는 서버의 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로 실행하세요:

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

더 나아가려면#