api-building

Files (11)

• SKILL.md
• architecture.md · references/
• app.js · references/mini-project/api/
• error.js · references/mini-project/api/helpers/
• mysql.js · references/mini-project/api/helpers/
• response.js · references/mini-project/api/helpers/
• auth.js · references/mini-project/api/middlewares/
• model.js · references/mini-project/api/model/
• user.js · references/mini-project/api/model/
• users.js · references/mini-project/api/routes/
• package.json · references/mini-project/

SKILL.md (first lines)

# API Building

Use this skill when an API should follow this default structure:

- Node.js + Express.
- `express.Router()` modules.
- ESM imports only.
- Named exports only. Never default export.
- `model/` for entity classes and persistence.
- `routes/` for API endpoints.
- `helpers/` for utilities that are not routes, middleware, or entities.
- `middlewares/` for auth and other pre-route logic.
- Only `GET`, `POST`, `PUT`, and `DELETE` endpoints.

## Required Structure

```text
src/
	app.js
	routes/
	model/
	helpers/
	middlewares/
```

## Responsibility Split

- `app.js`: compose Express, shared middleware, and route mounts.
- `routes/*.js`: parse input, validate request data, run request-scoped business logic, and shape HTTP responses.
- `model/*.js`: entity classes, persistence methods, normalization, relation loading.
- `helpers/*.js`: response helpers, database helpers, date utilities, mailers, render helpers, or other support code.
- `middlewares/*.js`: JWT auth, request guards, and reusable cross-cutting logic.

- Routes talk to model instances, not raw SQL.
- Only models use the database driver.
- Passwords are hashed with `bcrypt`.
- Auth defaults to JWT bearer tokens.
- Helpers are for support logic, not endpoint handlers and not direct entities.
- Keep route logic explicit, but keep persistence and entity behavior inside models.
- **Maintainability & Simplicity**: Default to simple, direct, non-overengineered code. Avoid unnecessary abstraction layers, duplicate helper functions, or excessive complexity. Keep code robust, safe, performant, and easy to maintain.

## Mandatory Security Defense (Auto-Triggered)

Whenever building or refactoring API endpoints, automatically apply [`security-defense-and-mitigation`](../security-defense-and-mitigation/SKILL.md) under the Proactive Security Rule:

1. **Authentication & Password Safety**: Hash all passwords with `bcrypt` (work factor ≥12). Secure JWTs with strong signing secrets from environment variables, explicit expiry (`expiresIn: '1h'`), and store tokens in `HttpOnly; Secure; SameSite=Strict` cookies or standard `Authorization: Bearer` headers.
2. **Authorization & IDOR/BOLA Defense**: Never trust client-supplied resource ownership (e.g. `req.body.userId`, `/users/:id`). Verify that the authenticated session identity matches the target entity's owner before reading, mutating, or deleting rows.
3. **Input Validation & Sanitization**: Validate all `req.params`, `req.query`, and `req.body` inputs in routes before touching models. Disallow mass assignment (whitelist permitted fields). Reject or sanitize malformed, overlong, or unexpected keys.
4. **Injection Prevention**: All SQL queries inside models must use parameterized queries via [`mysql-helper`](../mysql-helper/SKILL.md). Never concatenate user input into SQL strings.
5. **Rate Limiting & Bot Defense**: Apply rate-limiting middleware to auth endpoints (`/login`, `/register`, `/forgot-password`) to prevent brute-forcing.
6. **HTTP Security Headers**: Apply standard security headers (CSP, HSTS, X-Content-Type-Options, X-Frame-Options) across API responses.

## Endpoint Pattern

Prefer this request flow:

1. Read params, query, and body in the route.
2. Validate the required inputs in the route.
3. Instantiate the relevant model class.
4. Call model methods.
5. Return JSON through response helpers.

## Error Response Format

Error responses emitted by API error middleware must return HTTP status codes along with machine-readable error codes (`code`) and default messages (`error`, `message`) to enable frontend localization:

```json
{
  "error": "Name is required.",
  "code": "NAME_REQUIRED",
  "message": "Name is required."
}
```

Include a stable, machine-readable `code` string in all 4xx/5xx responses so frontend clients can map error codes to localized translation files.

## References

- Read `references/architecture.md` for the generic architecture rules.
- Read `references/mini-project/` for a small starter API that follows this structure.
- Pair this with [`security-defense-and-mitigation`](../security-defense-and-mitigation/SKILL.md), [`clean-code-and-oop`](../clean-code-and-oop/SKILL.md), [`mysql-helper`](../mysql-helper/SKILL.md), [`entity-models`](../entity-models/SKILL.md), and [`web-frontend`](../web-frontend/SKILL.md) when needed.

From werlang/user-skills, MIT.

More from werlang/user-skills