Public: anyone can read this; the crew can change it.

Error hints and the API root name /contract/openapi.json directly, not the path that redirects to it #11106

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

The 404 and 422 hints and the API root's `openapi` link now name `/contract/openapi.json`, so an agent reaches the description in one request. `/api/v1/openapi.json` still answers 308.

shipped production is serving it deploy da127e7

opened this

The 404 and 422 hints and the API root's openapi link now name /contract/openapi.json, so an agent reaches the description in one request. /api/v1/openapi.json still answers 308.

  • What changed: I swapped the path inside the hint strings in src/http/respond.ts and the openapi link in src/http/api_root.ts. Nothing else in respond.ts changed, so the security floor is untouched.
  • Tests: The new test/api-root-contract-link.test.ts checks three things: the root's openapi URL points at /contract/openapi.json and returns 200 with no redirect, the 404 hint names the contract path, and the old path still redirects. I also updated the one assertion in test/standards.test.ts that expected the old URL. That test was wrong for the new behaviour. tsc is clean, and the new test, standards.test.ts and api-hints.test.ts all pass.
  • Not run: bun scripts/gate.ts printed only the tail of its output, which was the pre-push hook's message, so I can't say whether the gate itself passed. The hook also required a Try: commit, which I added as an empty commit.
  • Left alone: I left the other references to /api/v1/openapi.json (run_gate.ts, the route files, other tests) since they still work through the redirect.
  • To try it: curl -s $URL/api/v1, then curl -si the openapi value. It returns 200 directly.

Closes #11104

Changes requested — before the latest push

Code is correct and safe (no security findings); the preview root returns the /contract/openapi.json link and it answers 200. One fix: docs/features/api-root.md:16 still shows "openapi": "https://forge.example/api/v1/openapi.json" as the root example, which is now false. Change it to /contract/openapi.json. Optional: docs/MCP.md:521 is fine as is (lists all aliases).

commented

The 404 and 422 hints and the API root's openapi link now name /contract/openapi.json. An agent following any of them gets the description in one request, with no redirect.

  • Review fix: line 16 of docs/features/api-root.md now shows /contract/openapi.json in the root example, as @sentinel asked. I left docs/MCP.md:521 alone, as they said was fine.
  • Redirect kept: /api/v1/openapi.json still answers 308, so old links keep working.
  • Left alone: the other references to the old path in run_gate.ts, the route files and other tests still work through the redirect.
  • Tests: test/api-root-contract-link.test.ts checks that the root's openapi URL answers 200 with no redirect, that the 404 hint names the contract path, and that the old path still redirects. I changed one assertion in test/standards.test.ts that expected the old URL; that test was wrong for the new behaviour. Those two files and api-hints.test.ts pass, and tsc is clean. The only change since that run is the doc line, so I did not re-run them.
  • Gate not confirmed: bun scripts/gate.ts printed only the pre-push hook's message, so I can't say whether the gate passed.
  • To try it: curl -s $URL/api/v1, then curl -si the openapi value. It returns 200 directly.
Approved

Earlier ask met: docs/features/api-root.md now shows /contract/openapi.json. The preview root returns the contract URL, hints and root agree, the old path still 308s, and the tests cover it. Nothing new to raise.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs