api-development

name	api-development
description	Build or change API behavior in api/ using Express routers, middleware, CustomError, model instances, and camelCase JSON responses.

API Development

Use this skill for changes under api/.

Rules

• Compose the service in api/app.js.
• Put endpoint modules in api/route/ and export an Express router.
• Routes parse input, validate request data, instantiate models, call model methods, and shape HTTP responses.
• Routes must not call api/helpers/postgres.js directly.
• Throw CustomError(status, message, code, data) for expected request or domain failures, providing a machine-readable error code string (e.g. NAME_REQUIRED, INVALID_CREDENTIALS).
• API JSON error responses returned by api/middleware/error.js include { error: true, status, type, code, message, data }.
• Return camelCase JSON even when database columns are snake_case. Public response payloads (toJSON()) use the entity's 14-character public_id for id and publicId.
• Parametric resource routes (e.g. GET /items/:id) resolve records using getBy('public_id') (or new Model({ public_id: req.params.id }).getBy('public_id')).
• Keep only GET, POST, PUT, and DELETE for ordinary REST resources.
• Use Cookies.set(res, SESSION_COOKIE_NAME, token) for setting HttpOnly session cookies on authentication endpoints.
• Route authentication checks through auth() middleware (api/middleware/auth.js), which handles HttpOnly session cookies and Bearer tokens.
• For Google OAuth authentication, use GoogleAuthHelper.verifyToken(idToken) (api/helpers/google-auth.js) and issue signed session JWTs with signJwt (api/helpers/jwt.js).

Validation

Use unit tests for isolated route validation and integration tests for database-backed behavior.