API Catalog Discovery with RFC 9727

An API catalog should answer a narrow question: which APIs does this publisher intentionally offer, and where are their maintained descriptions? RFC 9727 gives that answer a standard discovery entry at /.well-known/api-catalog.

The RFC does not ask every website to publish a catalog. It applies to HTTPS publishers that operate APIs. Discovery metadata should follow a supported service with an owner, version policy, and retirement process. Creating the well-known resource first reverses that dependency.

That boundary matters for automated clients. A catalog entry looks like an invitation to integrate, even when the target began as an internal route.

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.

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 would return a successful discovery result while naming no APIs. It would add an ownerless public artifact, invite clients to poll it, and create pressure to place the next internal route into the existing structure. Omission is the accurate response when a publisher has no public API catalog.

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.

RFC 9727 makes API discovery interoperable. The engineering obligation begins with having an API worth discovering.