API Catalog Discovery with RFC 9727

An API catalog should lead an engineer to an interface they can use: its contract, authentication requirements, supported versions and owner. A reachable URL without that information is a poor integration starting point.

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 an 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.

Select the supported integration surfaces

Build the catalog from the service inventory. Distinguish supported public APIs from form handlers, server actions, probes and administrative routes. An internal HTTP endpoint does not acquire a compatibility commitment simply because it appears in a catalog.

An empty catalog is valid, but gives clients no API to discover. Publish entries when the listed services have maintained descriptions and a clear lifecycle. Name who updates or removes each entry when its contract changes.

Verify publication and retirement

Generate the required Linkset JSON from release-controlled data. Check anchors, relation types and intended public targets. Exercise GET, HEAD, media-type, redirect and cache behavior against the public endpoint, including external catalog targets.

Then retire a test API version. Its entry should disappear while supported versions remain discoverable. Keep that check in the release process; the first successful GET does not show that the catalog will stay accurate.