Instruction file imported from dima-vlkdmn/ai-task-agent (.cursor/rules/api-design.mdc). Copyright stays with the author.

API Design

Route Handler Pattern

export async function METHOD(request: NextRequest, ctx?: RouteContext<"...">) {
  // 1. Rate limit check (AI/expensive endpoints only)
  // 2. Parse body: request.json().catch(() => null)
  // 3. Validate: Schema.safeParse(body) → validationErrorResponse on failure
  // 4. Call application layer in try/catch → toErrorResponse in catch
  // 5. Return Response.json(result, { status: 200 | 201 })
}

Error Response Shape

Every error response — 400, 404, 429, 500 — uses this exact shape:

{ "error": { "code": "STRING_CODE", "message": "Human readable message" } }

Validation errors add details:

{ "error": { "code": "VALIDATION_ERROR", "message": "Invalid input", "details": {...} } }

Status Codes

Error Utilities (from src/lib/http.ts, src/lib/errors.ts)

toErrorResponse(err)                   // use in every catch block
validationErrorResponse(zodError)      // use when safeParse fails
Errors.notFound("Task not found")      // use for 404 — returns null from repo
Errors.rateLimited(retryAfterSeconds)  // use in rate limit guard

Naming Conventions

GET    /api/tasks           → list all
POST   /api/tasks/from-text → create from AI (action route)
PATCH  /api/tasks/[id]      → update one field

No DELETE endpoint in MVP scope.