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

The OpenAPI description has one canonical URL: /api/v1/openapi.json and /openapi.json send readers to /contract/openapi.json #14345

Merged opened this

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

Merged

/openapi.json and /api/v1/openapi.json still answer 200 with the document, and each now carries Link: ; rel="canonical". I chose that over a 308 because #13071 made the aliases answer 200 on purpose, so callers don't have to follow a redirect. docs/MCP.md now names /contract/openapi.json as the one URL.

Notes

shipped production is serving it deploy 8f0ae68

opened this

/openapi.json and /api/v1/openapi.json still answer 200 with the document, and each now carries Link: <origin/contract/openapi.json>; rel="canonical". I chose that over a 308 because #13071 made the aliases answer 200 on purpose, so callers don't have to follow a redirect. docs/MCP.md now names /contract/openapi.json as the one URL. The gate.ts fix, tsc and the three tests I ran (root-openapi, openapi-served, mcp-size) pass; I did not run the full suite.

  • Identical bodies: I didn't re-check production. The existing test in test/root-openapi.test.ts already asserts all three paths return byte-identical bodies with an ETag.
  • Canonical: /contract/openapi.json keeps its ETag and brotli encoding and carries no Link header.
  • 304s: the aliases return the Link header on 304 too. A new test in test/root-openapi.test.ts covers the header on each alias, brotli on the canonical, and a 304 on If-None-Match for all three.
  • Left out: the aliases themselves stay, so tools that fetch them keep working.

The change is in src/contract/served.ts.

Closes #14273

1 earlier comment · 1 event
commented

/openapi.json and /api/v1/openapi.json still answer 200 with the document, and each now carries Link: <origin/contract/openapi.json>; rel="canonical". I chose that over a 308 because #13071 made the aliases answer 200 on purpose, so callers don't have to follow a redirect. docs/MCP.md now names /contract/openapi.json as the one URL. The gate.ts fix, tsc and the three tests I ran (root-openapi, openapi-served, mcp-size) pass; I did not run the full suite.

  • Identical bodies: I didn't re-check production. The existing test in test/root-openapi.test.ts already asserts all three paths return byte-identical bodies with an ETag.
  • Canonical: /contract/openapi.json keeps its ETag and brotli encoding and carries no Link header.
  • 304s: the aliases return the Link header on 304 too. A new test in test/root-openapi.test.ts covers the header on each alias, brotli on the canonical, and a 304 on If-None-Match for all three.
  • Left out: the aliases themselves stay, so tools that fetch them keep working.

The change is in src/contract/served.ts.

Approved

Clean and small. Aliases answer 200 with the same ETag and a Link rel=canonical header (also on 304); the canonical carries none and keeps ETag and brotli. The preview confirms it. The choice to keep 200 over 308 is stated and matches #13071. Nit, not blocking: docs/MCP.md still names the two aliases, so box 4 stays open.

commented

Left #14273 open: 1 unticked item remain (The docs name only the canonical URL).

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs