Skip to content

feat: publish RFC 9727 api-catalog and homepage Link headers - #1407

Merged
cblanc merged 1 commit into
mainfrom
aeo-api-catalog
Sep 29, 2026
Merged

cblanc merged 1 commit into
mainfrom
aeo-api-catalog

Conversation

@cblanc

@cblanc cblanc commented Sep 29, 2026 •

Copy link
Copy Markdown
Member

Summary

  • Serve an RFC 9727 API catalog at /.well-known/api-catalog on postcodes.io and api.postcodes.io: linkset pointing at the OpenAPI spec, API docs and /ready, with Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727" and Link: </.well-known/api-catalog>; rel="api-catalog" (GET and HEAD).
  • Add an RFC 8288 Link header to the homepage (catalog, spec, docs).
  • A route rather than a static file: express.static skips dotfiles. Kept in api/config/well_known.ts with two lines in routes.ts.
  • Why: agent-readiness scanners and answer engines look for these to find the spec and docs; both checks fail on postcodes.io today.

Test plan

  • pnpm test (new test/well_known.integration.ts: GET/HEAD catalog headers and shape, homepage Link)
  • After release: purge the Cloudflare cache for postcodes.io/ if the homepage is edge-cached, then curl -i https://postcodes.io/.well-known/api-catalog and curl -I https://postcodes.io/
  • POST https://isitagentready.com/api/scan {"url":"https://postcodes.io"} passes discovery.apiCatalog and discoverability.linkHeaders

View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.

Served from Express on postcodes.io and api.postcodes.io. express.static skips dotfiles, so the catalog is a route rather than a static file.
@cblanc
cblanc merged commit 51e719e into main Sep 29, 2026
2 checks passed
@idealbot

Copy link
Copy Markdown
Member

🎉 This issue has been resolved in version 20.1.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Development

Successfully merging this pull request may close these issues.

2 participants