Skip to content

API docs: publish pretty on every route and the caching/ETag contract - #81

Open
usehoplite[bot] wants to merge 2 commits into
mainfrom
api/p3-docs-followup
Open

usehoplite[bot] wants to merge 2 commits into
mainfrom
api/p3-docs-followup

Conversation

@usehoplite

@usehoplite usehoplite Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Follow-up to the merged API stack (#74, #77, #79, #80). All four are on main; this corrects the generated API documentation so it describes the code that actually shipped.

Why

The OpenAPI work (#76) documented the API as it was before the caching/ETag segment landed, and the merge of #79 took #76's text over the #79 wording. The result on main:

  • pretty is documented only on /recommend and /recommend/providers (shared/openapi-params.mjs), while the code accepts it on every data route — handleGet/withETag re-format centrally whenever pretty=1 or pretty=true is present. So the spec understates the API for /models, /stats, /images, /videos, /estimate, /compare, /providers, /orgs, /use-cases, / and /models/{id}/history.
  • The caching contract is undocumented. Responses carry a strong ETag, answer If-None-Match with a bodyless 304, send Cache-Control: public, max-age=300, stale-while-revalidate=600 on 200 GETs (no-store on errors), and HEAD returns GET's status and headers. None of that appeared in the published spec or the docs page.

That matters because llms.txt and the WebMCP tooling point agents at /openapi.json as the source of truth. An agent reading it would not know it can revalidate with an ETag (saving the whole payload) and would not know pretty is available outside the recommendation routes.

What changed

  • One shared PRETTY parameter definition, reused everywhere rather than restated per endpoint, registered on all fourteen data routes in shared/api-meta.mjs and their PARAMETER_DOCS entries.
  • The document info.description now states: compact JSON by default with pretty=1 opt-in, strong ETag with If-None-Match → bodyless 304, the 300s/600s cache policy with no-store on errors, and HEAD returning GET's status and headers without a body.
  • public/openapi.json and public/docs/api/index.html regenerated.

No runtime code changes — documentation only.

Verification

TW_PARITY_LIVE=0 node --test test/*.test.mjs   → 1081 tests, 1073 pass, 0 fail
node scripts/generate-seo.mjs                  → ok
node scripts/verify-seo.mjs                    → ok
node scripts/bust-cache.mjs && node scripts/minify-json.mjs → ok

Checks that matter here, all passing: every registered query parameter is documented with a type and description, documented parameters do not exceed the registered set, and the committed openapi.json matches what the generator produces. I also asserted directly against the generated file that pretty is present on all twelve routes and that the info block mentions ETag and 304.

Follow-up found in the final audit (commit 7e9fc7f)

A direct docs-vs-runtime parity check — exercising the real handler on all 14 documented paths rather than trusting the registry — found the last gap: GET /images/{id} and GET /videos/{id} both honour pretty=1 (verified on a real record: 280 B compact vs 405 B indented) but neither documented it. Both are now registered and documented, and a new test pins pretty on every route in the generated document, so a router change that accepts a parameter without documenting it fails CI. That is the check that would have caught the original drift.

The same audit confirms the rest of the contract end to end: status parity for pretty=1 on every path, real indentation, a strong ETag on GET, 304 with an empty body for If-None-Match, the exact Cache-Control string on 200s, no-store on errors, and HEAD matching GET's status and ETag with no body. No mismatches remain.

Final counts: 1081 tests, 1073 pass, 0 fail.

The generated OpenAPI document described the API as it was before the
caching/ETag work merged: `pretty` was documented only on the two
recommendation routes even though every data route honours it, and the
ETag / 304 / Cache-Control / HEAD behaviour was undocumented.

- One shared PRETTY parameter definition, reused on every data route:
  /, /use-cases, /stats, /orgs, /providers, /models, /models/{id}/providers,
  /models/{id}/history, /estimate, /compare, /images and /videos.
- The document info now states compact-by-default JSON, the strong ETag with
  If-None-Match -> bodyless 304, the 300s cacheable GET with a 600s
  stale-while-revalidate window, no-store on errors, and HEAD returning GET's
  status and headers without a body.

public/openapi.json and public/docs/api/index.html are regenerated.

Verified: 1080 tests / 1072 pass / 0 fail, including the 15 OpenAPI tests and
the committed-spec freshness check.

Co-authored-by: Hoplite <288093033+usehoplite[bot]@users.noreply.github.com>
@usehoplite
usehoplite Bot requested a review from thelaggingway as a code owner November 18, 2026 14:20
A parity audit against the running handler found the last gap: GET
/images/{id} and GET /videos/{id} both honour pretty=1 (verified: 280B
compact vs 405B indented for the same record) but neither documented it, so
the spec still understated two routes after the previous commit.

- Register `pretty` on both media detail endpoints in shared/api-meta.mjs and
  document it in PARAMETER_DOCS.
- Add a test pinning `pretty` on every route in the generated document, so a
  router change that accepts a parameter without documenting it fails CI
  instead of shipping a spec that lies. This is the check that would have
  caught the original drift.

public/openapi.json and public/docs/api/index.html are regenerated.

Verified: 1081 tests / 1073 pass / 0 fail; a direct docs-vs-runtime audit
exercising all 14 paths (status parity, real indentation, ETag, 304, cache
policy, HEAD parity) reports no mismatches.

Co-authored-by: Hoplite <288093033+usehoplite[bot]@users.noreply.github.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant