# REST API

> Use when building or reviewing Node.js REST API endpoints, middleware, input validation, authentication, authorization, database access, and error handling.

- Skill: `tomevault-io/rest-api-8` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/rest-api-8`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/rest-api-8/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/rest-api-8

---


# SKILL: REST API Patterns

Read this when: adding endpoints, handling auth, connecting to DB.

---

## Project Structure

```
src/
  routes/       # route definitions only — no logic here
  controllers/  # request/response handling
  services/     # business logic — pure functions, no req/res
  middleware/   # express middleware (auth, validate, error)
  db/           # database client and queries
  types/        # shared TypeScript types
  app.ts        # express app setup
  server.ts     # listen — separate from app for testing
```

---

## Key Rules

```
1. Validate all input at boundary — use zod, not manual checks
2. Never expose internals in error responses
3. Always call next(error) in async controllers — never swallow
4. Register error middleware LAST in app.ts
5. Validate env vars at startup — fail fast before serving traffic
6. Never return passwordHash or secrets in responses — use select:{}
```

---

## HTTP Status Codes

| Code | When |
|------|------|
| 200  | Success (GET, PUT, PATCH) |
| 201  | Created (POST) |
| 204  | Success, no body (DELETE) |
| 400  | Bad request / validation error |
| 401  | Not authenticated |
| 403  | Authenticated but not authorized |
| 404  | Resource not found |
| 409  | Conflict (duplicate) |
| 422  | Unprocessable (valid format, bad data) |
| 429  | Rate limited |
| 500  | Server error (log it, hide details) |

---

## References

- [references/controller-patterns.md](references/controller-patterns.md) — validation (zod), auth middleware (JWT), controller, error middleware, DB pattern, env vars

---
> Source: [prachwal/claude-config](https://github.com/prachwal/claude-config) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-15 -->