Перейти к содержимому
supastack
Обзор документации
WebTanStack Start

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.