REST APIを構築

アウトソーシングで最も一般的な納品物はAPIです。モバイルチームはバックエンドを必要とし、クライアントはフロントエンドを切り離したいと考え、パートナー統合には標準化されたインターフェースが必要です。正しい方法でAPIを構築する — 一貫したエラーレスポンス、適切なステータスコード、入力バリデーション、認証、そしてドキュメント — には通常1日かかります。Sun Agent Kitはそれを集中した午後に圧縮し、概念実証ではなく本番レビューに対応したコードを生成します。

概要

目標: 認証とCRUD操作を備えた完全に機能する、ドキュメント化されたREST APIを設計・実装する
所要時間: 30〜60分（手動では6〜12時間）
使用エージェント: planner、implementer、tester、doc-writer
コマンド: /sk:plan、/sk:cook、/sk:test、/sk:docs

前提条件

• Sun Agent Kitがインストール済みで、プロジェクトスキャフォールドが整っていること（最初から始める場合は /sk:bootstrap を実行）
• データベースが稼働しており、マイグレーションツールが設定済みであること
• 必要なリソース、リレーションシップ、操作の明確な説明
• 認証ストラテジーが決定済みであること（JWT、APIキー、OAuth — エージェントに伝える）
• スキャフォールドにすでに希望するフレームワークとORMが含まれていること（Express + Prisma、Fastify + Drizzle など）

ステップバイステップのワークフロー

ステップ1：APIエンドポイントを設計する

/sk:plan "design a REST API for a task management system: users, projects, tasks. Users own projects, projects contain tasks. Tasks have status (todo/in-progress/done), priority (low/medium/high), due dates, and assignees. CRUD for all resources. JWT auth. Role-based access: project owners can invite members."

処理内容: エージェントが以下を実行します：

1. 既存のフレームワーク、ORM、ルートパターンのプロジェクト構造を分析
2. 認証、プロジェクト、メンバー、タスク操作をカバーする完全なエンドポイントマップを設計
3. 番号付きステップとタスクチェックリストを含む実装計画を plans/ に保存

ステップ2：データベーススキーマを生成する

/sk:cook "implement the Prisma schema for users, projects, project_members, and tasks per the API design in plans/phase-task-api.md — then generate and run the migration"

処理内容: エージェントが以下を実行します：

1. 必要なすべてのモデルとリレーションシップを含むPrismaスキーマを作成
2. APIが最も頻繁に実行するクエリ用のインデックスを追加
3. マイグレーションを生成してデータベースに適用

ステップ3：CRUDエンドポイントを実装する

/sk:cook "implement all endpoints from plans/phase-task-api.md — controllers, services, route handlers, input validation with zod, and proper HTTP status codes for all success and error cases"

処理内容: エージェントが以下を実行します：

1. 適切な認証情報処理でauth エンドポイント（登録、ログイン）を実装
2. オーナーシップとメンバーシップのアクセス制御でプロジェクトエンドポイントを実装
3. フィルタリングと権限チェックでタスクエンドポイントを実装
4. すべての変更エンドポイントにZodバリデーションスキーマを適用
5. タイプチェックパスを実行してTypeScriptエラーを解消

ステップ4：テストを実行する

/sk:test "write and run integration tests for all endpoints — cover the happy path, auth failures, permission checks (non-owner trying to delete), and validation errors"

処理内容: エージェントが以下を実行します：

1. ハッピーパスとエラーケースをカバーするauth、プロジェクト、タスクのテストファイルを作成
2. テストデータベースに対してフルテストスイートを実行
3. コントローラー、サービス、スキーマのカバレッジをレポート

ステップ5：APIドキュメントを生成する

/sk:docs "generate API reference documentation for all endpoints — include request/response examples, error codes, and authentication notes"

処理内容: エージェントが以下を実行します：

1. すべてのルートハンドラーとZodスキーマを読み込む
2. PostmanまたはInsomniaにインポートできるOpenAPI 3.1仕様を生成
3. すべてのエンドポイントのcurl例を含む人間が読めるAPIリファレンスを作成

完全な実例：ユーザー・プロジェクト・タスクを持つタスク管理APIを構築する

シナリオ: クライアントのモバイルチーム（iOS/Android）がプロジェクト管理アプリのバックエンドを必要としています。データモデルのメモと画面一覧を含むNotionドキュメントを送ってきます。あなたの成果物は、PostmanにインポートできるドキュメントとともにAPIを動作させることです。タイムライン：水曜日の朝から金曜日の終業まで。

水曜日の朝、スタート:

# 1. ゼロから始める場合はブートストラップ
/sk:bootstrap "Express TypeScript REST API — PostgreSQL with Prisma, JWT auth, Zod validation, Vitest for tests, no frontend"

# 2. クライアントのNotionドキュメントからAPI全体を計画する
/sk:plan "task management API: users register/login, projects (CRUD, invite members), tasks (CRUD, status workflow, assignees, due dates, filters). Client mobile app will consume this. JWT auth throughout."

# 3. まずデータベーススキーマを構築する
/sk:cook "implement Prisma schema per the plan — focus on data integrity: FK constraints, indexes for the queries the mobile app will run (tasks by project, tasks by assignee)"

# 4. すべてのエンドポイントを実装する
/sk:cook "implement all endpoints per plans/phase-task-api.md — don't add anything not in the plan. Make sure every error response is JSON with { error: string } shape so the mobile team can handle errors consistently."

# 5. 包括的なテストを書く — クライアントはCIでこれらを実行する
/sk:test "integration tests for all endpoints — use a real test database, not mocks. Cover: auth flows, permission boundaries, filter combinations, edge cases like deleting a project with tasks"

# 6. OpenAPI仕様を生成する — モバイルチームが求めているもの
/sk:docs "generate API reference documentation — OpenAPI 3.1 spec importable into Postman, plus a curl-heavy API.md for quick reference"

# 7. コミット
/sk:git cm "feat: task management REST API — users, projects, tasks, JWT auth"

結果: 木曜日の正午までに、クライアントのモバイルチームはPostmanワークスペースにOpenAPI仕様を持ち、ステージングでAPIが稼働しています。終業時にはそれが自分たちの画面と一致することを確認します。金曜日は統合フィードバックへの対応のためのバッファです。

時間の比較

ベストプラクティス

1. cook プロンプトにエラーレスポンスの形式を指定する ✅

モバイルチームは汎用的に処理できるよう一貫したエラーレスポンスを必要とします。エージェントに伝えてください：「すべてのエラーは適切なHTTPステータスコードとともに { error: string, code?: string } を返すこと」。これにより各エンドポイントがエラーを異なる形式でフォーマットするのを防ぎます。

2. アクセス制御ルールを明示的に記述する ✅

「ロールベース」は曖昧です。具体的に記述してください：「プロジェクトオーナーのみがメンバーを招待できる。オーナーとメンバーの両方がタスクを作成できる。タスクの作成者またはアサイニーのみがタスクを削除できる。」曖昧な認可ルールはセキュリティが不十分または不整合な実装を生みます。

3. /sk:cook でエンドポイントを実行する前にPrismaスキーマをレビューする ✅

スキーマが間違っていれば、その上に構築されたすべてのエンドポイントが問題を引き継ぎます。次のステップに進む前に、生成されたスキーマを読むために5分を取ってください。

4. 計画なしに /sk:cook にすべてを一度に構築させる ❌

/sk:cook "build me a task management API" を計画なしに実行すると、クライアントのデータモデルと一致しない可能性のある汎用的な構造が生成されます。常に先に計画し、計画に従ってcookを実行してください。

5. 「後で追加する」という理由でOpenAPI仕様をスキップする ❌

「後で」は決して来ません。初期ビルドの一部として仕様を生成してください。/sk:docs で数分かかるだけで、クライアントのモバイルチームとの何時間もの往復を節約できます。

トラブルシューティング

問題：Prismaのマイグレーションが制約エラーで失敗する

解決策: /sk:fix --quick "Prisma migration failed: [paste error]" を実行してください。通常は外部キーの順序またはnull可能制約の問題です。エージェントは素早く解決します。

問題：テストがテストデータベースへの「接続拒否」で失敗する

解決策: .env.test ファイルの DATABASE_URL が本番ではなくテストデータベースを指していることを確認してください。/sk:ask "how should the test database be configured in this project?" を実行して確認してください。

問題：OpenAPI仕様が実際のエンドポイントの動作と一致しない

解決策: docsエージェントはルートハンドラーとスキーマを読み込みます。ハンドラーに文書化されていない動作（手動レスポンスのオーバーライド、ミドルウェアの副作用）がある場合は、関連するミドルウェアについての明示的な注記を含めて /sk:docs を再実行してください。

問題：/sk:cook がサービスレイヤーを作成するが、プロジェクトがそれを使用していない

解決策: パターンをプロンプトで指定してください: /sk:cook "put all business logic in route handlers, no service layer"。エージェントはデフォルトでコードベースの既存の規約に従いますが、上書きすることができます。

次のステップ

• 認証を実装 — 新しいAPIに完全な認証フローを追加する
• 新機能を追加 — 追加エンドポイントとビジネスロジックでAPIを拡張する
• バグを体系的に修正 — QAまたはモバイルチームがAPIに対して問題を報告した場合

重要なポイント: クライアントのモバイルチームが動作するAPIエンドポイントのために2日間待つべきではありません。しっかりとした計画に基づく /sk:cook で、エンドポイント、テスト、OpenAPI仕様を1つの午前中に届けます。