API Catalog Discovery with RFC 9727

I would be reluctant to list an endpoint in an API catalog unless another engineer could build against it using the documentation alone. Discovery makes an interface easier to find, but it also tells clients that the interface is intentional and supported.

RFC 9727, published in June 2025 as a Standards Track RFC, defines /.well-known/api-catalog for that purpose. It gives publishers a common entry point and a required Linkset JSON representation without dictating where the APIs themselves live.

A contact form handler and a versioned developer API may both accept HTTP requests. They carry very different compatibility and support commitments. An accurate catalog preserves that distinction.

GET and HEAD have different jobs

A publisher supporting RFC 9727 must resolve an HTTPS GET request to the well-known URI and return an API catalog document. The publisher chooses where the catalog document lives, so the well-known URI can resolve or redirect to another location under the publisher's control.

The same publisher must resolve HEAD /.well-known/api-catalog with a response that includes a Link field carrying the applicable relation or relations. HEAD lets a client inspect discovery metadata without transferring the catalog body. Its response still needs to describe the representation consistently with GET.

Test both methods through the production CDN and origin. A framework may route GET correctly while treating HEAD as an automatic response that omits the intended link. Redirect behavior, cache rules, authentication middleware, and content negotiation can also differ at the edge.

RFC 9727 registers the api-catalog link relation. A publisher may use that relation in an HTTP response field or document to point at a catalog URI. Clients should parse it using the Web Linking rules in RFC 8288, including multiple link values and target attributes, instead of splitting on commas.

The relation can also appear on ordinary publisher responses, giving clients a path to discovery before they know the well-known URI. Keep every advertised catalog location consistent. Two responses that name different catalogs create an ownership question clients cannot resolve from syntax alone.

Linkset JSON is the required representation

Every conforming API catalog must be available as the JSON serialization defined by RFC 9264:

GET /.well-known/api-catalog HTTP/1.1
Host: developer.example
Accept: application/linkset+json

HTTP/1.1 200 OK
Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"

Other formats may be offered through content negotiation, but they don't replace application/linkset+json. An organization with an existing catalog format still needs the required Linkset representation with, at minimum, hyperlinks to API endpoints. The RFC recommends the profile parameter shown above so a consumer can identify the RFC 9727 document profile.

A Linkset expresses links grouped by context. In JSON, anchor identifies the link context. It is not a display label. Resolve it as a URI and confirm that it identifies the API or catalog context the surrounding relations describe.

RFC 9727 permits several useful relation patterns. The registered item relation can identify an API that belongs to the catalog. Relations from RFC 8631 can attach supporting resources:

service-desc points to a machine-readable API description, such as an OpenAPI document;
service-doc points to human-readable documentation;
service-meta points to other machine-readable metadata;
status points to operating status information.

Those relations carry meaning. Don't place an OpenAPI document under service-doc or use status for a marketing page merely because the target exists. Clients may route each relation into different processing and trust decisions.

Catalogs can also link to other catalogs with rel="api-catalog". That supports organizations whose APIs span several domains, but nesting needs a cycle limit and a clear ownership boundary. A crawler should cap recursion, total bytes, redirects, and distinct hosts.

Review a catalog entry as an integration contract

Consider a fictional instrument supplier with a public calibration-results API and an internal job scheduler. The public catalog can link the results endpoint, its OpenAPI document, and its usage policy. The scheduler stays out even if a shared gateway makes it technically reachable.

I would ask a reviewer to follow the entry without internal knowledge: determine which version is supported, how to request credentials, and where an error is documented. If that requires guessing, improve the API's supporting material before advertising it. This is an editorial check as well as a schema check; a perfectly valid linkset can still give a client the wrong expectations.

Maintenance determines whether discovery remains accurate

RFC 9727 devotes substantial attention to operations because a catalog becomes public inventory. It should enter the same change-control path as the APIs it lists.

For each release, verify endpoint links, OpenAPI documents, documentation, supported versions, authentication requirements, usage policy, and status resources. API retirement needs an explicit catalog removal step. Leaving a withdrawn version discoverable can send clients toward an unsupported surface after application traffic has already moved elsewhere.

The catalog itself needs monitoring. Request GET and HEAD, validate the media type and Linkset shape, follow every public target from an external network, and alert an accountable team when a required target fails. Set cache lifetimes that match the organization's ability to update the document.

Treat publication as a security review, too. The RFC warns about sensitive personal or business metadata, internal endpoints, and unnecessary write access. External requests should be read-only. Catalog updates and rewrite rules belong to limited deployment roles. HTTPS, rate limits, response-size controls, and normal denial-of-service protections still apply.

A catalog doesn't authorize access. It also doesn't prove an API is safe. Clients must apply the API's authentication, authorization, input validation, and tenant controls after discovery.

The contact form is not a public API

TKOResearch operates a route that processes contact submissions. That route supports a site form; it isn't a developer product with a stable programmatic contract, public version policy, client credentials, integration documentation, or compatibility commitment.

Putting the route in an API catalog would misclassify an application boundary as a supported integration surface. It could also encourage automated submission against a path protected for its actual purpose by validation and rate limits.

An empty catalog isn't useful for this site. That is a product decision, not a claim that every empty inventory is inherently unsafe. The meaningful deliverable would be a supported public API and a maintained entry for it.

TKOResearch will not add /.well-known/api-catalog until a public API exists with product ownership, a threat model, authentication policy, lifecycle plan, operational monitoring, and maintained descriptions. For TARE, those requirements should be part of the API launch gate rather than follow-up documentation.

A defensible adoption sequence

Start with the service inventory. Separate public APIs from form handlers, server actions, health probes, and administrative routes. For each public API, name its owner and supported contract.

Then build the required Linkset JSON from release-controlled data. Validate anchors and relation types, publish only intended public targets, and exercise exact GET, HEAD, media-type, redirect, and cache behavior. Add external target checks to operations. Finally, test removal with a retired version so the catalog lifecycle is proven before clients depend on it.

Before release, retire a test API version and verify that its catalog entry disappears while supported versions remain discoverable. That exercise checks the part most likely to be forgotten after the first successful GET.