Decide the gh posture for the v1 rename #215

Closed AtlantisPleb opened this 2d ago 1 comment

Evidence

Shipped in the release at 8c53d09, promoted 2026-08-26.

1 pushes receipt

Problem

gh hardcodes https://%s/api/v3/ for any non-github.com host (verified against gh 2.89.0's binary; no path override exists), so after the rename gh only works if /api/v3 stays as a permanent alias. Octokit takes a full baseUrl and only needs shape. docs/episode-triage.md:1207 currently claims "gh and octokit work unchanged" — false post-rename without the alias.

Decide

Keep the /api/v3 alias permanently for gh compatibility (record it in INVARIANTS.md), or drop gh compatibility explicitly and fix the claim. Then either way, correct the episode-triage line. The temporary-alias deletion issue depends on this decision.

AtlantisPleb opened this issue 2d ago
AtlantisPleb closed this as completed in 1666117 2d ago

A AtlantisPleb Author 2d ago

Decided: the API is GitHub-shaped, not gh-compatible, and /api/v3 stays a dated migration alias.

Measured against gh 2.89.0 and the live application on 2026-08-25, keeping the prefix buys no working gh command:

Command	Request	Result
`gh issue list`	`POST /api/graphql`	404
`gh issue view 215`	`GET /api/v3/meta`	406
`gh api repos/OWNER/REPO/issues`	`GET /api/v3/repos/...`	200
`gh api https://openagents.com/api/v1/repos/OWNER/REPO/issues`	`GET /api/v1/...`	200

The ported commands never touch REST, so the alias cannot rescue them. The one surface it does serve, the gh api passthrough, already reaches /api/v1 given a full URL. Supported clients are the openagents CLI and anything you point at a base URL, such as Octokit with baseUrl: https://openagents.com/api/v1.

Committed in 1666117:

docs/decisions/0009-serve-a-github-shaped-api-not-a-gh-compatible-one.md — the decision, the evidence, and what gh support would actually cost (a GraphQL endpoint and /meta, not a path segment).
INVARIANTS.md FORGEAPI-002 — every versioned route is declared at /api/v1, every emitted URL names /api/v1, and the rewrite plug is the only file under lib/ naming the old prefix, proved by test/openagents_web/api_version_posture_test.exs.
priv/docs/rest-api.md — a "Choose a client" section naming gh as unsupported and why.
docs/episode-triage.md — the episode 273 "gh and octokit work unchanged" line now carries its correction.
Fixed one live consequence: POST /api/v1/traces returned a url field naming /api/v3/traces/{id}, a link that would have gone dead with the alias.