| name | api-specs |
| description | Document static JSON and loader contracts under docs/api-specs/ before changing src/static-api/. Use when adding recipes, loaders, types, filters, or data the UI depends on; pairs with recipes-static-api, page-specs, and recipes-tdd. |
API specs (static API — API-driven)
This project has no HTTP backend. "API-driven" means versioned JSON + typed loaders are specified in docs before code changes.
Layout
docs/api-specs/
index.md
README.md
loaders/<contract>.md # getRecipeBySlug, catalog filters, etc.
data/recipes-schema.md # optional: canonical JSON field reference
Implementation lives in src/static-api/ — see recipes-static-api.
Loader contract spec contents
Each loaders/*.md must include:
- Summary — what UI/features achieve with this loader
- Source — JSON path (
src/static-api/data/..., public URL)
- Types — TypeScript types (
Recipe, etc.)
- Operations — function signatures, return shapes, errors
- Validation — required fields, slug rules, empty catalog behavior
- Page dependencies — links to
docs/product-specs/pages/*.md
- Features table —
XX-API-n IDs, status, Tests column → src/static-api/loaders/*.test.ts
Use docs/api-specs/loaders/TEMPLATE.md.
Hard rules
- New public loader functions are documented before merge
- JSON shape changes update data schema doc and loader spec together
- Every documented error/edge case has a loader test (or dated exception in Decisions)
- Page specs list API dependencies; loader specs list Page dependencies — both sides updated
Implementation order
- Update loader spec (
planned)
- Failing Vitest loader test
- JSON + loader implementation
- UI/hooks consuming loader
- Mark
complete; link tests in spec and feature-catalog
Definition of done
- Spec matches
src/static-api behavior
- Loader tests linked from Tests column
docs/api-specs/index.md updated
