Make the API docs and the discovery document match the server - #25
Open
0bserver07 wants to merge 1 commit into
Open
Make the API docs and the discovery document match the server#250bserver07 wants to merge 1 commit into
0bserver07 wants to merge 1 commit into
Conversation
The /api/v1 discovery document listed GET /{owner}/{repo}/api/commit/{sha}/merge-queue,
which has no route, and pointed docs at https://git.example.com/api on every host. The
endpoint line is gone and docs is now derived from the request base like the other URLs
in the document (AGENTS.md section 5: nothing in crates/ knows a hostname).
web/API.md section 5 and the API page said every JSON write needs admin. Creating a
repository and starting an op need write (admin.rs, ui.rs); deleting a repository and
writing policy or settings need admin (admin.rs, policy.rs, settings.rs). The page also
had no row for settings and dropped the /api segment from every repository path.
API.md, docs/CONTRACT.md and the SDK comment promised an [integrations] settings section
that walgit-config rejects; the section 6 checklist gave browser_base as /api/v1 instead
of /api-browser/v1; the overview shape pointed at a Go file that does not exist; the
bundle design doc still named /services/install.sh.
Tests: api_v1 asserts docs is derived from the discovery base, and a new test pins the
write gates (a write token gets 403 on PUT and DELETE of policy and settings, an admin
token gets 204 and 200). The walgit-config settings test asserts [integrations] is
refused.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This was referenced Aug 29, 2026
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.
The discovery document at
/api/v1advertisedGET /{owner}/{repo}/api/commit/{sha}/merge-queue, which has no route, and pointeddocsathttps://git.example.com/apino matter which host answered. Both are gone: the endpoint line is removed anddocsis now derived from the request base like every other URL in the document (AGENTS.md section 5: nothing incrates/knows a hostname).The docs disagreed with the code in a few more places I hit while reading the API contract:
web/API.mdsection 5 said every write on the JSON surface needs admin. Creating a repository and starting an op need write (admin.rs:19,ui.rs:1084); deleting a repository and writing policy or settings need admin (admin.rs:48,policy.rs:682,settings.rs:136).web/src/pages/ApiPage.tsx) said the same wrong thing about policy, three lines under a row that 527c7d1 had already corrected; it had no row for settings at all, and dropped the/apisegment from every repository path.web/API.md,docs/CONTRACT.mdand the SDK comment inweb/sdk/repos.tspromised an[integrations]settings section;SETTINGS_SECTIONSin walgit-config accepts four sections and a PUT with[integrations]is a 400.browser_baseas/api/v1instead of/api-browser/v1; the overview shape pointed at anoverview.gothat does not exist;docs/BUNDLE_URI_DESIGN.mdstill named/services/install.shinstead of/services/public/install.sh.Tests:
api_v1now asserts thatdocsis derived from the discovery base, and a new test pins the write gates (a write token gets 403 on PUT and DELETE of policy and settings, an admin token gets 204 and 200). The walgit-config settings test asserts[integrations]is refused.Checked with
cargo test -p walgit-server --test api_v1,cargo test -p walgit-configandpnpm run build(oxlint, tsc). The clippy step in CI fails on main today for reasons unrelated to this change (see #24); clippy reports nothing in the lines touched here.