Defer the JSON API until something consumes it

Supersedes decision 17, which expected endpoints to appear one at a time.
Nothing calls /api at all, so even that would be handlers with no callers and
golden tests guarding shapes nothing reads.

The contract stays in the spec as a design — it is what stops the shape
changing under a future client — marked as not built so the spec doesn't
claim behaviour the code lacks. later.md records what to build first when a
consumer appears.
This commit is contained in:
Esa Kataja
2026-07-31 22:38:03 +03:00
parent f1e907bac3
commit 69eea8d707
3 changed files with 29 additions and 3 deletions
+17
View File
@@ -151,6 +151,23 @@ Notes for whoever builds it:
---
## The JSON API
Designed and specified in [spec.md §8](./spec.md) — object shapes, endpoints, error codes,
pagination — and deliberately not implemented, because nothing calls it (decision 43).
When something does:
- Build only the endpoints that consumer needs, as `jsonOf(...)` adapters over the same data
functions the pages already use, so the domain rules cannot diverge between the surfaces.
- Add the golden-file tests at the same time, one per object shape. They are what makes a renamed
field a test failure rather than a silent break in a client you cannot update.
- CORS is a one-line middleware, added the day the consumer is on a different origin. Not before.
- The most likely first consumer is a native client (see above), and the endpoints it needs are
login, the queue, a song with its reviews, and posting a review — four routes, not twenty-one.
---
## Filters on the browse list
`/songs` is newest-first with no filters. Once there are a couple of hundred songs, "which ones