---
name: adding-an-api-route
description: Use when adding a new Next.js API route to this project. Keeps routes thin and logic in the right layer instead of inline in the route file.
---

# Adding a new API route

1. Check `study-app-implementation-plan.md`'s Section 9 file tree first. If
   this route is already named there, follow that path and method exactly
   rather than inventing a different shape.
2. Create the route file under `src/app/api/<resource>/route.ts`, or
   `src/app/api/<resource>/[id]/route.ts` for a single-resource endpoint.
3. The route handler does exactly three things: validate the request body
   (reuse a Zod schema from `lib/validation/` if one already exists for this
   shape, write one if it doesn't), call one function in the matching
   `services/<resource>Service.ts`, and return a `NextResponse`. No Prisma
   calls and no business logic directly in the route file.
4. If the logic doesn't fit an existing service file, add a new exported
   function to the closest matching one. Only create a new
   `services/<resource>Service.ts` if this is genuinely a new resource, don't
   bolt unrelated logic onto an existing service to avoid creating a file.
5. Run `npm run lint` before considering the route done. A failing
   `max-lines` or `filename-case` error means something is in the wrong
   place, not that the rule needs an exception.