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 /ja/docs/modules/api.md (or send Accept: text/markdown).

API モジュール

バージョン管理された公開コントラクト、キー配管、OpenAPI サーフェス。

このガイドについて質問

始める前に

[ファイル] → [フォルダーを開く] を使用して、Visual Studio Code でダウンロードした supastack プロジェクトを開き、[ターミナル] → [新しいターミナル] を選択します。リポジトリルートは、package.json、アプリ、およびパッケージを含むフォルダーです。そこで以下のコマンドを実行し、ターミナルを開いたままにしておきます。コマンドが認識されない場合は、続行する前にツールのインストールガイドを完了してください。

まずプラットフォームのチュートリアルをお読みください。サーバーは、ブラウザまたは電話のリクエストに応答するアプリプロセスです。 Web は apps/web/.env.local を読み取り、Expo は apps/mobile/.env.local を読み取り、データベース移行コマンドは root .env を読み取ります。データベースなしの /dashboard デモは、Postgres の移行が必要な実際の /auth アカウントとは別のものです。電話またはデスクトップのみのチェックアウトには、別途実行される Web バックエンドが必要です。

corepack pnpm --filter @supastack/web dev

インストールとセットアップ

packages/api は公開 REST サーフェスの信頼できる情報源です: リクエスト、レスポンス、エラーエンベロープの zod スキーマ、加えて /api/v1/openapi で配信される OpenAPI ドキュメント(openApiDocument)。ルートハンドラーは形状を再定義するのではなくこれらのスキーマを組み立てます。

API キーはワークスペースごとに sk_<env>_ プレフィックス付きで発行され、定数時間比較のハッシュで保存され、スコープ(デフォルトは読み取り)を持ちます。api-keys.ts が作成・検索・失効を所有します。

apiV1 = "/api/v1"

schemas: currentWorkspace, entitlement,
  modelRequirements, createAiTaskRequest,
  aiTask, aiTaskResult, apiError

openApiDocument → GET /api/v1/openapi

実装ワークフロー

既存バージョン内でエンドポイントを追加します: スキーマを拡張し、エラーエンベロープを維持し、OpenAPI サーフェスを再生成して /api/docs の正確さを保ちます。破壊的変更は静かな形状変更ではなく新バージョンを取得します。

提示されたキーから呼び出し元のワークスペースを解決し、Web アプリと同じエンタイトルメント・検証ルールを適用し、キーごとにレート制限します。

検証とトラブルシューティング

各ルート形状をパッケージスキーマに対してコントラクトテストします。不明・失効・スコープ不足のリクエストがすべて文書化されたエラーエンベロープで失敗すること、OpenAPI ドキュメントが有効な JSON のままであることを確認します。