design-api

Design API

Write consistent API endpoints for a model using existing codebase patterns.

Workflow

1. Read the DB model, an existing handler, router pattern, shared middleware.
2. Reuse first: response helpers, pagination, validation schemas, auth guards, error classes.
3. Define the contract (confirm omitted verbs / nested routes with the user):

GET    /resources           → list (paginated)
GET    /resources/:id       → single resource or 404
POST   /resources           → create, return 201 + created resource
PUT    /resources/:id       → full replace or 404
PATCH  /resources/:id       → partial update or 404
DELETE /resources/:id       → 204 No Content or 404

1. Write the handlers:

• Each handler does one thing: validate → call service/repo → respond
• Never query the DB directly in a handler — go through a service or repository layer
• Use shared error handling — never duplicate try/catch boilerplate per handler
• All responses use the same shape — { data } success, { error, message } failure
• 404s from the service layer must propagate to a consistent error response
• Never expose internal DB errors or stack traces to the client

1. Run /write-tests on the new handlers.
2. Verify:

npx tsc --noEmit        # no type errors
npm test -- --testPathPattern=<resource>  # targeted test run

Guardrails

• No speculative routes.
• Skip filtering/sorting/pagination unless asked.
• No service/repository layer yet? Use /refactor-codebase first.
• Handlers thin — push logic past ~30 lines to the service layer.

References

• REFERENCE.md — shape, errors, validation, pagination, test templates.