Перейти к содержимому
Логотип Аурабаза
аурабаза

REST API — Обзор

Aurabase необработанная поверхность HTTP. Совместим со всеми языками. Базовый URL-адрес, аутентификация, формат ответа, коды ошибок — затем подробности по конечной точке в /docs/api/.

Справочник7 мин читатьУровень ссылкаПересмотрено 15 апр. 2026 г.

Эта страница была переведена автоматически. Английская версия является авторитетной.

Начало, проект в пути#

URL-адрес — это проекта. Каждый проект обслуживается в собственном поддомене https://<slug>.<apex> (локально http://<slug>.localhost:8080), а шлюз разрешает проект с хоста: в путях не прописывается идентификатор проекта. Studio › Settings › Connection показывает этот URL-адрес, а NEXT_PUBLIC_AURABASE_URL удерживает его. Шлюз предоставляет два плана: план данных (SDK и приложения, :8080 локально) и план управления (Студия и администрирование, :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 — только в проекте Postgres, обслуживаемом PostgREST, который интерпретирует его сам. Путь aura-db (проект MongoDB или Postgres с отключенным PostgREST) игнорирует этот заголовок: он читает только 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 или 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, свободный текст) мы различаем.

ошибка, выданная службой Aurabasejson
{
  "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 специально сохраняет 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, 100 требуется/с с пакетом 1000 по умолчанию (настраивается через RATE_LIMIT_RPS / RATE_LIMIT_BURST). Для каждой роли нет отдельного уровня.
  • Чувствительность к аутентификации (login, register, forgot-password, magic-link, email-otp/send, sms/send, refresh, mfa/verify-login): 5 запросов в минуту на каждый IP, пакет 3. Кроме того, квота на проект: 30 подключений попыток/час на IP по умолчанию, настраивается в настройках проекта. В разработке (AURA_ENV=development, локальный стек) ограничение маршрутизатора ослаблено (пакет 100), поэтому вы можете выполнять итерации; всегда применяются квоты проекта, указанные в Studio › Аутентификация › Конфигурация › Ограничение скорости.
  • Необработанный SQL (/raw): 30 запросов/мин, пакет 10. IA: 10 запросов/мин, пакет 5.
Внимание

Переполнение → 429 Too Many Requests с заголовками X-RateLimit-Limit и X-RateLimit-Remaining (присутствуют при любом ответе от шлюза), плюс X-RateLimit-Reset и Retry-After при отказе.

Полное дерево для каждой услуги#

У каждой конечной точки есть отдельная страница с параметрами, кодами ответов, примерами на 5 языках и действующим железнодорожным кодом.

База данныхАутентификацияХранилищеРеальное времяФункции

SDK для вашего языка пока нет.#

Опубликованного пакета Python или Dart пока нет (об этом говорит и студия). Вышеупомянутый 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'));
}

Чтобы пойти дальше#