API Service

Your project

Live preview — CLAUDE.md

# My API

TailorMD recipe: **API Service**

## Stack

- **API style:** REST
- **Runtime:** Node.js
- **Database:** Postgres
- **ORM / query layer:** Drizzle

## Folder map

```
src/
  routes/          # HTTP handlers or resolvers — thin layer only
  services/        # business logic
  db/
    schema/        # migrations, models
    queries/       # data access
  middleware/      # auth, logging, rate limits
  lib/             # shared utilities
tests/
  unit/
  integration/
docs/
  openapi.yaml     # REST only — keep in sync with routes
```

## Non-negotiables

- Never commit `.env` or secrets
- Validate all inputs at the API boundary (Zod, Pydantic, or equivalent)
- Business logic lives in `services/`, not route handlers
- All schema changes go through migrations — no manual prod edits
- Return consistent error shapes; never leak stack traces to clients
- OpenAPI spec must match implemented routes (REST)

## Naming and style

- Files: `kebab-case` (or language convention)
- Handlers/resolvers: verb + resource (`getUser`, `createOrder`)
- DB tables: `snake_case`
- Env vars: `SCREAMING_SNAKE_CASE`
- Prefer explicit types; no `any` in TypeScript codepaths

## Commands

```bash
# Adjust for Node.js and your package manager
npm run dev              # local server
npm run build            # compile (if applicable)
npm run test             # unit + integration
npm run lint             # static analysis
npx drizzle-kit migrate  # or prisma migrate / alembic upgrade
```

## Ship checklist

Before merging or deploying:

- [ ] Types/build pass
- [ ] Lint clean
- [ ] Tests pass for changed paths
- [ ] Migrations applied and reversible
- [ ] OpenAPI / schema docs updated (REST)
- [ ] No secrets in diff
- [ ] Env vars documented in `.env.example`
- [ ] Health check endpoint responds

## API style (REST)

- **REST:** resource-oriented URLs, correct HTTP verbs, pagination on list endpoints
- **GraphQL:** typed schema, N+1 prevention, auth on resolvers
- **tRPC:** input validation on every procedure, no unauthenticated mutations

## Database (Postgres + Drizzle)

- Use parameterized queries only — no string interpolation
- Index foreign keys and frequent filter columns
- Seed data for local dev; never seed prod credentials