Summary

  • RFC 9727 gives a publisher a standard place and link relation for an API catalog. It standardises discovery of an asserted collection; it does not attest that every item is reachable, owned, authorised, monitored or healthy.
  • The catalog has its own authority, context, cache and availability. Nested and cross-domain catalogs expand the map but also create boundaries that must be recorded rather than silently inherited.
  • Removing an item is evidence that a publication changed. Safe retirement requires separate proof about exposure, traffic, dependencies, change execution, rollback and post-withdrawal observation.

A clean list can describe a dirty estate

RFC 9727, published in February 2025 on the IETF Standards Track, defines two deliberately small pieces of infrastructure: the api-catalog link relation and /.well-known/api-catalog. A publisher can answer GET at that location, advertise it in a Link header, and return a catalog in Linkset JSON. Links with relation item identify APIs; links with relation api-catalog can lead to subordinate catalogs.

That is useful because API discovery is often an archaeological exercise. Hostnames live in deployment files, developer portals omit internal variants, old gateways remain reachable after a product relaunch, and nobody can confidently say which interface is authoritative. A stable discovery point turns a private spreadsheet or oral tradition into a machine-readable assertion.

The word assertion is the boundary. A catalog says that its publisher chose to relate a context to a target at the time represented by that response. Web Linking supplies typed relationships, not operational certificates. A valid item does not show that DNS resolves from a particular network, a gateway accepts connections, credentials exist, the target operator recognises the catalog publisher, or a transaction completes. Conversely, an unlisted listener does not disappear.

This matters for both security and governance. OWASP API9:2023 identifies outdated versions, undocumented hosts and incomplete inventories as an attack-surface problem. RFC 9727 can reduce that blindness. It can also make a polished catalog the new source of false confidence if leaders count links while exposed infrastructure drifts outside the publication process.

The authority belongs to each edge

The simplest deployment places the catalog under a publisher-controlled domain. Even there, the well-known path does not make every target first-party. A catalog can point to a partner API, a managed service or a historical endpoint. The evidence is the publisher's claim that the relationship belongs in its catalog. Ownership and operational control still need their own records.

RFC 9727 also allows a publisher unable to host the well-known resource to point towards a catalog on another domain. That solves a practical constraint without turning the target host into an all-purpose authority. The redirect or Link response, TLS identities, timestamps and catalog hash form an authority chain. If one of those links changes, the reader should see a new chain rather than assume continuity from a familiar title.

Nested catalogs make the same issue recursive. A group catalog can lead to a product catalog, which can lead to regional catalogs. Each hop can have a different maintainer, release clock and access boundary. RFC 9264 requires link context to be explicit because moving a linkset without its anchor can alter its meaning. The hierarchy is not a tree of inherited truth; it is a graph of dated claims.

A useful catalog receipt therefore records the responding domain, discovery path, redirects, TLS peer, response time, content type, profile, ETag or Last-Modified value, body hash and every explicit context-target-relation triple. It records first and last observation without turning either into a creation or deletion date. It identifies who can change the publication and who separately operates each target. These are proposed controls, not requirements added to RFC 9727.

A catalog has a cache clock; an API has an operating clock

A client can receive a technically valid catalog that no longer matches the estate. RFC 9111 explains freshness, validation and stale-response handling. An ETag can show that a representation did not change across two validations. It cannot show that an endpoint continued to run between them. A long freshness lifetime can make discovery efficient while delaying visibility of an emergency removal. A short lifetime can increase origin load without making updates accurate.

Four clocks should therefore remain distinct: when the publisher intended the catalog state; when the origin served it; when a cache validated or reused it; and when an operator changed an API or gateway. A fifth clock belongs to the observer. “Not in the catalog at 14:00” is defensible only with the response, cache path and observation time. It is not proof that the API stopped at 14:00.

RFC 9727 anticipates part of this operational burden. It recommends monitoring catalog availability and performance, correlating catalog use with subsequent API requests, removing stale entries, checking syntax and business rules, and refreshing catalogs through the release lifecycle. It also says the catalog complements, rather than replaces, an API-management framework. That sentence prevents the discovery mechanism from swallowing the control system it was meant to inform.

Catalog health is not item health

A monitoring probe can fetch /.well-known/api-catalog, validate Linkset JSON and follow every nested catalog. The entire exercise can be green while an item returns errors. The reverse is also possible: the catalog origin can fail while bookmarked API clients continue to transact successfully.

RFC 8631 registers a status link relation for a status resource. Such a link may help a reader find operational information, but it does not merge the status page, catalog and API into one measurement. Each can have a separate host, publisher and failure mode. Health evidence needs a named transaction, vantage point, authentication context and interval. A TCP connection, an HTTP response and a successful business operation remain different observations.

The same separation protects private systems. RFC 9727 warns that catalogs can reveal internal APIs and recommends review, TLS, limited write access, rate limiting and suitable access controls. Publication can widen an exposure map even when it grants no credentials. An internal hostname may assist an attacker or disclose architecture. “The catalog is protected” also says nothing about whether one listed API is unintentionally public. Catalog access and endpoint exposure must be tested independently.

Removing the card does not remove the socket

RFC 9727 notes that an audited catalog can help identify zombie APIs: interfaces that are unsupported, unmonitored or unpatched. That is a discovery benefit, not a shutdown instruction. A zombie is dangerous precisely because the administrative record and the running system have separated.

Deleting an item produces a publication event. It may reflect a correction, a transfer to another catalog, a temporary concealment, a replacement or a planned retirement. It does not close a listener, revoke a credential, remove a DNS record, drain a queue or update an unknown client. Nor does continued listing prove that an API is supported. The catalog and running estate can disagree in either direction.

A retirement receipt should join several independent records. Preserve the last catalog snapshot and the authorised decision. Record DNS, routing, load-balancer and gateway changes; the exact interface and environments affected; known owners and downstream jobs; usage evidence with its observation window and blind spots; credentials and integration flows; change acknowledgements; exception and rollback owners; and post-withdrawal probes. If a quarterly job, cached client or partner network was outside measurement, say so.

This article does not replace the existing BTW analysis of Deprecation and Sunset signals. Those headers address a resource's announced lifecycle. The narrower point here is about catalog topology: a removed relationship is not execution evidence. A server may keep answering after removal; a server may have vanished while its link persists. The evidence should preserve the disagreement instead of editing history until the records look aligned.

Sources

Specification and registries: RFC 9727, RFC Editor record, IETF Datatracker, IANA well-known URI registry, IANA link relation registry, RFC 9264, RFC 8288, RFC 8615, RFC 8631, RFC 9111, RFC 9745, RFC 8594, OWASP API9:2023.

Attributed analytical framework: Lu Heng — Note 64, Running-code primacy, Why BTW records reality.