For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ru/docs/modules/api.md (or send Accept: text/markdown).
Модуль API
Версионируемый публичный контракт, механика ключей и поверхность OpenAPI.
Прежде чем начать
Откройте загруженный проект supastack в Visual Studio Code, используя «Файл» → «Открыть папку», затем выберите «Терминал» → «Новый терминал». Корень репозитория — это папка, содержащая package.json, приложения и пакеты. Запустите команду ниже и оставьте терминал открытым. Если команда не распознается, завершите руководство по установке инструмента, прежде чем продолжить.
Сначала прочтите руководство по платформе. Сервер — это процесс приложения, который отвечает на запросы браузера или телефона. Веб читает apps/web/.env.local, Expo читает apps/mobile/.env.local, а команды миграции базы данных читают корневой .env. Демонстрация без базы данных / панели мониторинга отделена от реальных учетных записей / аутентификации, для которых необходимо перенести Postgres. Для оформления заказа только на телефоне или компьютере требуется отдельно работающий веб-сервер.
- Установите инструменты и получите код
- Изучение команд, файлов и конфигурации
- Пройдите руководство по первому запуску в Интернете
corepack pnpm --filter @supastack/web devНастройка и конфигурация
packages/api — источник истины для публичной REST-поверхности: zod-схемы запросов, ответов и обёртки ошибок плюс документ OpenAPI (openApiDocument), отдаваемый на /api/v1/openapi. Обработчики маршрутов компонуют эти схемы вместо переопределения форм.
API-ключи выпускаются по пространствам с префиксом sk_<env>_, хранятся хэшированными со сравнением за постоянное время и несут scope — по умолчанию read. api-keys.ts владеет созданием, поиском и отзывом.
apiV1 = "/api/v1"
schemas: currentWorkspace, entitlement,
modelRequirements, createAiTaskRequest,
aiTask, aiTaskResult, apiError
openApiDocument → GET /api/v1/openapiРабочий процесс внедрения
Добавляйте эндпоинты внутри существующей версии: расширяйте схемы, сохраняйте обёртку ошибок и регенерируйте поверхность OpenAPI, чтобы /api/docs оставался точным. Ломающие изменения получают новую версию, а не тихое изменение формы.
Разрешайте пространство вызывающего из предъявленного ключа, применяйте те же правила энтайтлмента и валидации, что и веб-приложение, и ограничивайте частоту по ключу.
Проверка и устранение неполадок
Контрактно тестируйте каждую форму маршрута против схем пакета. Проверьте, что неизвестные, отозванные и недостаточно-scoped запросы все завершаются задокументированной обёрткой ошибки, и что документ OpenAPI остаётся валидным JSON.