factory-api-route-engineer

Apply the api-route-engineer specialist workflow. Build endpoints grounded in the factory's API conventions, not bespoke per-route handlers. Load the canonical factory-api and factory-auth skills through the host's skill capability when needed.

How to think (in order)

1. API style? Apply the decision matrix from factory-api.md:

   • Server actions — default. One frontend consumer. Feature-folder colocation matters.
   • tRPC — ≥3 entities with cross-feature queries. Multiple consumers. Typed RPC.
   • REST / OpenAPI — only for external system callers.

   If the project already commits to one, use it. Don't mix.

2. What's the surface?

   • Mutation — create, update, delete, custom action
   • Query — list (paginated), detail (by ID), search, aggregation
   • Webhook — external system → your service

3. Auth tier?

   • publicProcedure — only for genuinely public endpoints (signup, public docs)
   • protectedProcedure — authed user, no org context
   • orgProcedure — authed user + org context (default for app endpoints)

4. Input shape? Per-endpoint Zod schema. For paginated lists:

   • limit: number().int().min(1).max(100).default(50)
   • offset: number().int().min(0).default(0)
   • orderBy: enum([...]).default('createdAt')
   • orderDir: enum(['asc','desc']).default('desc')
   • Plus per-feature filter object

5. Output shape? Three options:

   • List: { items: T[], total?: number } — include total if pagination needs it
   • Detail: T | null — return null on not-found, throw NotFoundError if the caller expected it
   • Mutation: the updated/created entity, or ActionResult<T> for server actions

6. Multi-tenant filter? Every query / mutation in orgProcedure filters by ctx.orgId. This is automatic enforcement, not "remember to add WHERE."

7. Pagination shape?

   • Offset — default for everything (admin tables, settings, normal CRUD)
   • Cursor — only for real-time feeds, append-only logs, or pagination-stable-under-inserts requirements (chat messages, audit log)

8. Aggregations in list? If the list view needs counts (e.g. "customer with vehicle count"), use a subquery / leftJoin + groupBy rather than a per-row round-trip:

   ctx.db.select({
     ...getTableColumns(customers),
     vehicleCount: count(vehicles.id),
   }).from(customers).leftJoin(vehicles, ...).groupBy(customers.id);
   

9. Error shape?

   • Throw AuthError, NotFoundError, ValidationError from src/lib/errors.ts
   • For server actions, catch at the boundary and convert to { error: 'message' }
   • For tRPC, throw TRPCError({ code, message })

10. Audit log? Fire-and-forget at the mutation boundary. Never await it on the critical path. See factory-security.md.