Repository navigation
API docs: publish pretty on every route and the caching/ETag contract - #81
Open
usehoplite[bot] wants to merge 2 commits into
Open
usehoplite[bot] wants to merge 2 commits into
usehoplite[bot] wants to merge 2 commits into
Conversation
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>
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:prettyis documented only on/recommendand/recommend/providers(shared/openapi-params.mjs), while the code accepts it on every data route —handleGet/withETagre-format centrally wheneverpretty=1orpretty=trueis present. So the spec understates the API for/models,/stats,/images,/videos,/estimate,/compare,/providers,/orgs,/use-cases,/and/models/{id}/history.ETag, answerIf-None-Matchwith a bodyless304, sendCache-Control: public, max-age=300, stale-while-revalidate=600on 200 GETs (no-storeon errors), andHEADreturns GET's status and headers. None of that appeared in the published spec or the docs page.That matters because
llms.txtand the WebMCP tooling point agents at/openapi.jsonas the source of truth. An agent reading it would not know it can revalidate with an ETag (saving the whole payload) and would not knowprettyis available outside the recommendation routes.What changed
PRETTYparameter definition, reused everywhere rather than restated per endpoint, registered on all fourteen data routes inshared/api-meta.mjsand theirPARAMETER_DOCSentries.info.descriptionnow states: compact JSON by default withpretty=1opt-in, strongETagwithIf-None-Match→ bodyless304, the 300s/600s cache policy withno-storeon errors, andHEADreturning GET's status and headers without a body.public/openapi.jsonandpublic/docs/api/index.htmlregenerated.No runtime code changes — documentation only.
Verification
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, andthe committed openapi.json matches what the generator produces. I also asserted directly against the generated file thatprettyis 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}andGET /videos/{id}both honourpretty=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 pinsprettyon 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=1on every path, real indentation, a strongETagon GET,304with an empty body forIf-None-Match, the exactCache-Controlstring on 200s,no-storeon errors, and HEAD matching GET's status and ETag with no body. No mismatches remain.Final counts: 1081 tests, 1073 pass, 0 fail.