Honest Health Endpoints: An Engineering Culture Note

A health endpoint that always says 'ok' is a lie with an HTTP status code. Ours report which backend is actually serving — in-memory or Postgres — because the fastest way to corrupt an engineering culture is to let the system flatter you.

The lie that ships first

Every web service grows a /health route, and most of them are born dishonest: return { status: 'ok' }. It compiles, the load balancer is happy, the dashboard is green. It also tells you nothing — and worse, it tells you nothing reassuringly.

We learned this the concrete way. Several of our stores follow an optional-dependency pattern: they run against a real in-memory implementation by default and transparently upgrade to Postgres when a database is reachable. It is a good pattern — the build never depends on infrastructure — but it has a failure mode: a misconfigured DATABASE_URL does not crash anything. The app runs, the demo works, and every write quietly evaporates on the next restart. A green { status: 'ok' } on top of that state is not a health check; it is an alibi.

What our health routes say instead

Every domain health route on this platform answers three questions:

1. Which backend is actually serving? Not which one is configured — which one the store facade is currently delegating to. If persistence says "in-memory" in an environment that should be durable, that is a finding, surfaced in one curl.
2. Does the real path work right now? The route exercises a minimal genuine operation — a one-row read through the actual store — rather than reporting on the process's continued existence.
3. Is the dependency even configured? databaseConfigured: false next to backend: "in-memory" distinguishes "running as designed for local dev" from "production is silently amnesiac".

The editorial store serving the very page you are reading follows the same discipline — /api/editorial/health will tell you honestly whether this article came from Postgres or from the bundled seed.

Why this is a culture note, not a tips post

The technical change is trivial — a getter on a facade and three JSON fields. The cultural change is the point: the system must not flatter its operators. A team whose dashboards are green by construction stops reading them, and then stops deserving them. A team whose health endpoints occasionally deliver bad news keeps the habit of looking.

Evidence over narration. It is the first rule in our engineering charter, and it applies to the software's claims about itself most of all.