# Design API

> Designs consistent, DRY REST API endpoints for models — handlers, routing, validation, errors — then generates test coverage. Use when the user asks to write an API, add endpoints for a model, build a REST layer, or create CRUD routes.

- Skill: `rockclaver/design-api` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add rockclaver/design-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rockclaver/design-api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: rockclaver (https://skillmd.com/u/rockclaver)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rockclaver/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
```

4. 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

5. Run `/write-tests` on the new handlers.
6. Verify:

```bash
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](REFERENCE.md) — shape, errors, validation, pagination, test templates.