Next.js API Patterns
Overview
Patterns for building API endpoints within the Next.js frontend (apps/web). This is the home for application-level CRUD and data-serving routes — the standard request/response API surface that powers the UI and external integrations. It also covers webhook receivers and OAuth callbacks.
Boundary: The NestJS services (apps/ai, apps/sync) handle background jobs, AI pipelines, queues, and sync processing. If the work involves those, use hamster-nest-api instead. If it's a synchronous API route that reads/writes data in response to a request, it belongs here.
When to Apply
- Building CRUD endpoints for application data in
apps/web/app/api/
- Creating data-serving API routes consumed by the frontend or external clients
- Building webhook endpoints (OAuth callbacks, external service webhooks)
- Handling OAuth authorization/callback flows in the web app
When NOT to Apply
| Scenario |
Use instead |
| Background jobs, queues, AI pipelines |
hamster-nest-api |
| Server actions (mutations from UI) |
hamster-react (server-actions rule) |
| NestJS controllers/services |
hamster-nest-api |
| Data fetching in server components |
hamster-react (data-fetching rule) |
Quick Reference
| Task |
Pattern |
Reference |
| API route handler |
enhanceRouteHandler with auth + schema |
references/rules/route-handlers.md |
Route Handler Pattern
Use enhanceRouteHandler from @kit/next/routes for all API routes:
// app/api/users/route.ts
import { z } from 'zod';
import { NextResponse } from 'next/server';
import { enhanceRouteHandler } from '@kit/next/routes';
const CreateUserSchema = z.object({
email: z.string().email(),
name: z.string().min(1),
});
export const POST = enhanceRouteHandler(
async ({ body, user, request }) => {
// body: validated against schema
// user: authenticated user
// request: NextRequest
const result = await createUser(body, user.id);
return NextResponse.json({ success: true, data: result });
},
{
auth: true,
schema: CreateUserSchema,
}
);
Common Use Cases in This Codebase
| Directory |
Purpose |
app/api/oauth/*/callback/ |
OAuth callback handlers (Linear, Notion, Slack, Jira, etc.) |
app/api/auth/cli/ |
CLI authentication flow |
app/api/blueprints/ |
Blueprint data endpoints |
app/api/methods/ |
Method data endpoints |
Server Actions vs Route Handlers
| Use Case |
Solution |
| Data mutation from client component |
Server Actions (enhanceAction) - see hamster-react |
| CRUD endpoints for app data |
Route Handlers (enhanceRouteHandler) |
| Data-serving APIs for external clients |
Route Handlers |
| Webhook endpoints |
Route Handlers |
| OAuth callbacks |
Route Handlers |
| CLI authentication flows |
Route Handlers |
Best Practices
- Prefer server actions for mutations triggered by the UI
- Use route handlers for webhooks, OAuth callbacks, and external-facing endpoints
- Always validate request body with Zod schema
- Handle errors gracefully - log internally, return generic messages
- Use proper HTTP status codes
References
references/rules/route-handlers.md - Complete route handler patterns and options
1---2name: hamster-nextjs-api3description: "Next.js API route handlers in apps/web. Use when building CRUD endpoints, data-serving API routes (app/api/), webhooks, or OAuth callbacks in the Next.js frontend. NOT for background jobs or AI pipelines (use hamster-nest-api instead)."4version: "1.1.0"5category: "Development"6metadata:7 source: https://skillmd.com/skills/gethamster/hamster-nextjs-api8---910# Next.js API Patterns1112## Overview1314Patterns for building API endpoints within the Next.js frontend (`apps/web`). This is the home for **application-level CRUD and data-serving routes** — the standard request/response API surface that powers the UI and external integrations. It also covers webhook receivers and OAuth callbacks.1516**Boundary**: The NestJS services (`apps/ai`, `apps/sync`) handle background jobs, AI pipelines, queues, and sync processing. If the work involves those, use `hamster-nest-api` instead. If it's a synchronous API route that reads/writes data in response to a request, it belongs here.1718## When to Apply1920- Building CRUD endpoints for application data in `apps/web/app/api/`21- Creating data-serving API routes consumed by the frontend or external clients22- Building webhook endpoints (OAuth callbacks, external service webhooks)23- Handling OAuth authorization/callback flows in the web app2425## When NOT to Apply2627| Scenario | Use instead |28| --- | --- |29| Background jobs, queues, AI pipelines | `hamster-nest-api` |30| Server actions (mutations from UI) | `hamster-react` (server-actions rule) |31| NestJS controllers/services | `hamster-nest-api` |32| Data fetching in server components | `hamster-react` (data-fetching rule) |3334## Quick Reference3536| Task | Pattern | Reference |37| --- | --- | --- |38| API route handler | `enhanceRouteHandler` with auth + schema | `references/rules/route-handlers.md` |3940## Route Handler Pattern4142Use `enhanceRouteHandler` from `@kit/next/routes` for all API routes:4344```typescript45// app/api/users/route.ts46import { z } from 'zod';47import { NextResponse } from 'next/server';48import { enhanceRouteHandler } from '@kit/next/routes';4950const CreateUserSchema = z.object({51 email: z.string().email(),52 name: z.string().min(1),53});5455export const POST = enhanceRouteHandler(56 async ({ body, user, request }) => {57 // body: validated against schema58 // user: authenticated user59 // request: NextRequest60 const result = await createUser(body, user.id);61 return NextResponse.json({ success: true, data: result });62 },63 {64 auth: true,65 schema: CreateUserSchema,66 }67);68```6970## Common Use Cases in This Codebase7172| Directory | Purpose |73| --- | --- |74| `app/api/oauth/*/callback/` | OAuth callback handlers (Linear, Notion, Slack, Jira, etc.) |75| `app/api/auth/cli/` | CLI authentication flow |76| `app/api/blueprints/` | Blueprint data endpoints |77| `app/api/methods/` | Method data endpoints |7879## Server Actions vs Route Handlers8081| Use Case | Solution |82| --- | --- |83| Data mutation from client component | Server Actions (`enhanceAction`) - see `hamster-react` |84| CRUD endpoints for app data | Route Handlers (`enhanceRouteHandler`) |85| Data-serving APIs for external clients | Route Handlers |86| Webhook endpoints | Route Handlers |87| OAuth callbacks | Route Handlers |88| CLI authentication flows | Route Handlers |8990## Best Practices91921. **Prefer server actions** for mutations triggered by the UI932. **Use route handlers** for webhooks, OAuth callbacks, and external-facing endpoints943. **Always validate** request body with Zod schema954. **Handle errors** gracefully - log internally, return generic messages965. **Use proper HTTP status codes**9798## References99100- `references/rules/route-handlers.md` - Complete route handler patterns and options