REST API — Обзор
Aurabase необработанная поверхность HTTP. Совместим со всеми языками. Базовый URL-адрес, аутентификация, формат ответа, коды ошибок — затем подробности по конечной точке в /docs/api/.
Начало, проект в пути#
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.
# 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=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-часовой интервал).
Лимит + смещение#
# Только портативная форма — работает на обоих движках.
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,
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:
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'));
}