How do I mock the Hacker News Firebase API locally?

Install stunt, add a one-service block to stunt.yaml (adapter: embedded:hn-style), and run stunt up. You get a local, stateful stand-in for Hacker News Firebase API v0 — 11 routes over rest — with no remote account, no network, and no bills.

Is the Hacker News Firebase API mock data synthetic?

Yes — entirely. The adapter returns generated data only; stunt's adapter lint rejects real-looking secrets and PII at build time. It simulates the shape and behavior of Hacker News Firebase API (routes, status codes, pagination, webhooks), never real records.

← all adapters

hn-style

simulates Hacker News Firebase API v0

restadapter v0.1.011 routes

verification

VMVM tier — no SDK suite yet· surface 11 · not implemented 3 · differs 4

use it

# add to stunt.yaml
services:
  hn:
    adapter: embedded:hn-style

# then
$ stunt up

The embedded: source extracts this adapter from the binary — no git clone, fully offline.

how to mock the Hacker News Firebase API locally

Install stunt, paste the service block above into stunt.yaml, run stunt up — then point your client at localhost instead of Hacker News Firebase API. It works offline, keeps state across requests and restarts, and every response is synthetic: the route shapes, status codes, pagination, and webhook delivery follow the real Hacker News Firebase API v0 surface — the data is fake, the behavior is real.

backing stores

itemsuserssessions

api surface (11)

generated from the adapter manifest — exactly what boots, nothing more

11 routes

GET/v0/topstories.json

GET/v0/newstories.json

GET/v0/beststories.json

GET/v0/askstories.json

GET/v0/showstories.json

GET/v0/jobstories.json

POST/login

GET/logout

POST/submit

GET/v0/item/{id}

GET/v0/user/{id}

VM-verified behaviors (10)

✓item reads resolve the .json route capture into the full Firebase story shape
✓comments link up via parent and kids, omit story-only fields, and count their subtree in descendants
✓unknown items and users answer 200 with the literal null, not a 404
✓story lists are bare integer arrays: top and best rank by score, new is newest-first
✓ask and show partition the story set by title prefix; jobs stay type-only and off the story lists
✓Firebase REST query params (print=pretty, orderBy, limitToFirst) are accepted and ignored
✓user reads resolve .json ids into created/karma/about/submitted with by/submitted agreeing
✓users without a bio omit about, matching the sparse Firebase shape
✓reads are public: no credential is required and a stray bearer gates nothing
✓maxitem and updates are not modeled: the read surface is the six lists plus item and user

Not implemented (3)

No GET /v0/maxitem.json or GET /v0/updates.json endpoints
No poll or pollopt item types; no deleted or dead item flags
No realtime updates (Firebase SSE watch) on item or list reads

Differs from the real API (4)

Write flow /login + /submit from a reference client; official Firebase API is read-only
Challenge injection after N submits (anti-abuse) mirrors mock_hn, configurable via KV
Firebase REST query params (print=pretty, orderBy, limitToFirst) are accepted and ignored
The .json suffix is optional on item reads; real Firebase requires it

full scorecard →

want more of the Hacker News Firebase API surface? adapters are YAML + Starlark — the authoring guide covers adding routes, fixtures, and state machines. Open an issue for anything big first, or just file a PR — merged routes ship in the next release.