v2-api-endpoints

name

v2-api-endpoints

description

Describes how to add Express routes under app/src/api/v2: validate middleware with Zod, shared @shared/validation (domain + http), server errors via the v2 errorHandler, responseUtils for JSON bodies, colocated supertest suites, extracting domain operations (DomainFailure, no HTTP in domain), and updating types/src/v2/endpoints for response shapes. Use when creating or changing v2 HTTP endpoints, route handlers, tests, validation wiring, or @offnominal/ndb2-api-types v2 exports; pairs with v2-database-queries for data access and domain-operations for shared business logic.

v2 API endpoints

Layout and wiring

• Route modules: app/src/api/v2/routes/<area>/<verb>_<pathShape>.ts (e.g. routes/predictions/get_predictions_{predictionId}.ts).
• Route type: export a Route from @shared/routerMap — a function (router: Router) => void that registers methods on the sub-router.
• Mounting: import the route in app/src/api/v2/index.ts, add it to the mapRoutes([...]) array for the appropriate prefix (/predictions, /seasons, etc.).
• Error middleware: errorHandler from middleware/errorHandler is already registered last on apiV2Router in index.ts. Do not remove or reorder it for new routes.

Validation: always validate + Zod

Use validate from app/src/api/v2/middleware/validate.ts for every part of the request that the handler reads:

• params — path segments (e.g. ).