Hosted Dolt API v1 docs - #149
Merged
Merged
Conversation
The DoltHub v2 generator was one 448-line script. Hosted's v1 API needs the same rendering — its spec deliberately shares DoltHub v2's error model, success envelope, and pagination conventions — so the rendering moves to scripts/lib/openapi-docs.mjs and generate-api-v2.mjs becomes config. The only DoltHub-specific behaviour left is the Database tag's sub-resource grouping, now an opt-in `groups` config rather than `if (tag === "Database")`. Two defects fixed along the way, which is why the v2 pages change: Schema links resolved one level too deep. Pages build to <page>/index.html and are served from <page>/, so a sibling-relative `models#model-user` from the user page resolved to .../user/models — dead on every generated v2 page, and in the hand-written authentication.md and migration.md too. Links are now site-root-relative; the rehype base-path plugin prefixes the site base. curl examples dropped required query parameters, so the command as printed was a 400. The SQL endpoints need ?ref=&q=; they now carry the spec's own example values. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Documents the new public REST API for the Hosted control plane, under Products > Hosted Dolt > API > v1, mirroring the DoltHub API layout. specs/hosted-v1.yaml is vendored from ld's hosted-web/packages/hosted/openapi/v1.yaml, the same way the DoltHub v2 spec is. user.md, deployment.md, and models.md are generated from it by scripts/generate-hosted-api-v1.mjs (npm run generate-hosted-api-v1) — never hand-edit them. The two READMEs and authentication.md are hand-written. The authentication page documents the hsat.v1. token prefix, the settings/tokens flow, the show-once secret, and the fixed expiry options, all of which live in ld rather than in the spec. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Re-vendors specs/hosted-v1.yaml from ld main (1c62599829e), replacing the copy taken from the taylor/hosted-api-v1-list-instances branch, and regenerates deployment.md and models.md from it. The changes are all prose — no endpoints, schemas, or fields moved (still 6 operations and 17 schemas). Two are rewordings of the create-deployment 5xx guidance and the pagination description. The third is a real contract detail: next_page_token is now documented as absent on the last page rather than "absent or empty", and `meta` is omitted entirely there. That last one also invalidated a hand-written sentence in v1/README.md, which told clients to treat an empty token as the end of results. Updated to match: presence of the token is the only check needed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The sections sit directly under API rather than behind a "v1" node — with one version shipped, that layer was a click with nothing to choose. Every path still carries /v1/, so adding a v2 later reintroduces the version layer without moving any of these URLs. The v1 overview page is kept in the tree as "Overview". It holds the endpoint table, response envelope, error model, and stability policy, so dropping the v1 node without it would have left that page reachable only by inbound link. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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
1 participant
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.
Documents the new public REST API for Hosted Dolt, under Products → Hosted Dolt → API → v1, mirroring the DoltHub API layout.
Spec vendored from
ldathosted-web/packages/hosted/openapi/v1.yaml(branchtaylor/hosted-api-v1-list-instances), the same wayspecs/dolthub-v2.yamlis.Shared generator
The DoltHub v2 generator was one 448-line script. Since the Hosted spec deliberately shares DoltHub v2's error model, success envelope, and pagination conventions, the rendering moved to
scripts/lib/openapi-docs.mjsand both generators are now thin config:scripts/generate-api-v2.mjs— DoltHub, keeps itsDatabasesub-resource grouping (now an opt-ingroupsconfig rather than a hardcodedif (tag === "Database"))scripts/generate-hosted-api-v1.mjs— Hosted (npm run generate-hosted-api-v1)The refactor was byte-identical on the DoltHub output before any behavior changes.
Pages
products/hosted/api/README.mdproducts/hosted/api/v1/README.mdproducts/hosted/api/v1/authentication.mdproducts/hosted/api/v1/{user,deployment,models}.mdAuthentication facts (
hsat.v1.prefix,/settings/tokens, show-once secret, 30/60/90/365-day expiry with no never-expires option, full user permissions) are verified againstldrather than invented — they live in the app, not the spec.Two fixes that also touch DoltHub v2
Both were pre-existing generator defects, so fixing them in the shared lib changed the v2 pages too. This is most of the diff in
products/dolthub/api/v2/.Broken schema links in shipped docs. Generated pages linked to
models#model-x. Those pages build to<page>/index.htmland serve from<page>/, so the link resolved one level too deep — every schema link on the live v2user/database/operationspages is currently dead, as were the sibling links in the hand-writtenauthentication.mdandmigration.md. Now site-root-relative; the rehype base-path plugin prefixes/docs.curl examples dropped required query params.
getDeploymentOptionsneeds?cloud=; DoltHub's SQL endpoints need?ref=&q=. Both printed commands that would 400.Verification
npm run build:doltpasses; frontmatter check passes (160 pages)llms.txtOne thing to confirm
cypress/fixtures/dolt-pages.tsdoesn't list the new pages — but it doesn't list the DoltHub v2 pages either. It's a GitBook migration-parity fixture used bycy:run:live, so adding pages that exist only in the new site would break that run. Worth a call on whether the dead-link crawler should cover these some other way.