Build a REST API

The most common outsourcing deliverable is an API: a mobile team needs a backend, a client wants to decouple their frontend, or a partner integration needs a standardized interface. Building an API the right way — consistent error responses, proper status codes, input validation, authentication, and documentation — typically takes a full day. Sun Agent Kit compresses that into a focused afternoon, producing code that’s ready for production review, not just a proof of concept.

Overview

Goal: Design and implement a fully functional, documented REST API with authentication and CRUD operations
Time: 30–60 minutes (vs 6–12 hours manual)
Agents used: planner, implementer, tester, doc-writer
Commands: /sk:plan, /sk:cook, /sk:test, /sk:docs

Prerequisites

• Sun Agent Kit installed with a project scaffold in place (run /sk:bootstrap if starting fresh)
• Database running and migrations tooling set up
• A clear description of the resources, relationships, and operations needed
• Authentication strategy decided (JWT, API key, OAuth — tell the agent which one)
• Preferred framework and ORM already in the scaffold (Express + Prisma, Fastify + Drizzle, etc.)

Step-by-Step Workflow

Step 1: Design the API Endpoints

/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."

What happens: The agent:

1. Analyzes the project structure for existing framework, ORM, and route patterns
2. Designs the full endpoint map covering auth, projects, members, and task operations
3. Writes an implementation plan with numbered steps and task checklist saved to plans/

Step 2: Generate the Database Schema

/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"

What happens: The agent:

1. Writes the Prisma schema with all required models and relationships
2. Adds indexes for the queries the API will run most frequently
3. Generates and applies the migration to the database

Step 3: Implement CRUD Endpoints

/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"

What happens: The agent:

1. Implements auth endpoints (register, login) with proper credential handling
2. Implements project endpoints with ownership and membership access control
3. Implements task endpoints with filtering and permission checks
4. Applies Zod validation schemas to all mutating endpoints
5. Runs a typecheck pass and resolves any TypeScript errors

Step 4: Run Tests

/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"

What happens: The agent:

1. Writes test files for auth, projects, and tasks covering happy paths and error cases
2. Runs the full test suite against a test database
3. Reports coverage for controllers, services, and schemas

Step 5: Generate API Documentation

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

What happens: The agent:

1. Reads all route handlers and Zod schemas
2. Generates an OpenAPI 3.1 spec importable into Postman or Insomnia
3. Writes a human-readable API reference with curl examples for every endpoint

Complete Example: Build a Task Management API with Users, Projects, and Tasks

Scenario: A client’s mobile team (iOS/Android) needs a backend for their project management app. They send a Notion doc with data model notes and a list of screens. Your deliverable is a working API with docs they can import into Postman. Timeline: Wednesday morning to Friday end of day.

Wednesday morning start:

# 1. Bootstrap if starting from scratch
/sk:bootstrap "Express TypeScript REST API — PostgreSQL with Prisma, JWT auth, Zod validation, Vitest for tests, no frontend"

# 2. Plan the full API from the client's Notion doc
/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. Build the database schema first
/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. Implement all endpoints
/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. Write comprehensive tests — the client will run these in 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. Generate the OpenAPI spec — this is what the mobile team asked for
/sk:docs "generate API reference documentation — OpenAPI 3.1 spec importable into Postman, plus a curl-heavy API.md for quick reference"

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

Result: By Thursday noon, the client’s mobile team has an OpenAPI spec in their Postman workspace and a running API on staging. They confirm it matches their screens by end of day. Friday is buffer for any integration feedback.

Time Comparison

Best Practices

1. Specify the error response shape in the cook prompt ✅

Mobile teams need consistent error responses to handle them generically. Tell the agent: “all errors must return { error: string, code?: string } with the appropriate HTTP status.” This prevents each endpoint from formatting errors differently.

2. Describe the access control rules explicitly ✅

“Role-based” is vague. Be precise: “only project owners can invite members; both owners and members can create tasks; only the task creator or assignee can delete a task.” Vague authorization rules produce insecure or inconsistent implementations.

3. Review the Prisma schema before running /sk:cook on endpoints ✅

If the schema is wrong, every endpoint built on top of it inherits the problem. Take 5 minutes to read the generated schema before proceeding.

4. Asking /sk:cook to build everything in one command without a plan ❌

/sk:cook "build me a task management API" without a plan produces a generic structure that may not match the client’s data model. Always plan first, then cook against the plan.

5. Skipping the OpenAPI spec because “we’ll add it later” ❌

“Later” never comes. Generate the spec as part of the initial build. It takes a few minutes with /sk:docs and saves hours of back-and-forth with the client’s mobile team.

Troubleshooting

Problem: Prisma migration fails with a constraint error

Solution: Run /sk:fix --quick "Prisma migration failed: [paste error]". Usually a foreign key ordering or nullable constraint issue — the agent resolves it quickly.

Problem: Tests fail with “connection refused” to the test database

Solution: Check your .env.test file has DATABASE_URL pointing to a test database, not production. Run /sk:ask "how should the test database be configured in this project?" to verify.

Problem: The OpenAPI spec doesn’t match the actual endpoint behavior

Solution: The docs agent reads route handlers and schemas. If handlers have undocumented behavior (manual response overrides, middleware side effects), re-run /sk:docs with an explicit note about the middleware involved.

Problem: /sk:cook creates a service layer but the project doesn’t use one

Solution: Guide the pattern in the prompt: /sk:cook "put all business logic in route handlers, no service layer". The agent follows your codebase’s existing conventions by default but can be overridden.

Next Steps

• Implement Authentication — add full auth flows on top of your new API
• Add a New Feature — extend the API with additional endpoints and business logic
• Fix Bugs Systematically — for when QA or the mobile team reports issues against your API

Key takeaway: A client’s mobile team should never wait two days for a working API endpoint — /sk:cook against a solid plan delivers endpoints, tests, and an OpenAPI spec in a single morning.