api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs
Extracted elements (27)
Nesting API catalog links (using the api-catalog relation in a catalog document) is supported to allow Publishers with large API portfolios to group APIs into smaller sub-catalogs by business or technology category, reducing catalog size and maintenance overhead.
The api-catalog well-known URI is intended to complement — not replace — existing API management frameworks. Publishers may incorporate /.well-known/api-catalog publication as a final pre- or post-release step in existing release management workflows.
The Linkset format (application/linkset+json) is mandated as the primary format because it provides a standardized, machine-readable structure for listing API links, while additional formats are permitted via content negotiation to accommodate publishers with existing API catalog formats.
The Publisher MAY make additional catalog formats available via HTTP content negotiation beyond the mandatory Linkset format. Non-exhaustive alternatives include APIs.json, RESTdesc, HAL, and the Schema.org WebAPI type extension.
When a Publisher's API catalog links to APIs hosted on a domain for which the Publisher is not the authority, the catalog MAY include a link to the third-party domain's own api-catalog using the 'api-catalog' link relation rather than listing those APIs directly.
A Publisher supporting the well-known URI SHALL resolve an HTTPS GET request to /.well-known/api-catalog and return an API catalog document, and SHALL resolve an HTTPS HEAD request with a response including a Link header with the api-catalog relation.
For APIs distributed across multiple domains, it is RECOMMENDED that the Publisher publish the api-catalog well-known URI at each API domain, returning the same catalog document, with one instance designated canonical and others redirecting to it.
If a Publisher already lists APIs in a format other than Linkset but wishes to use /.well-known/api-catalog, they MUST also implement a Linkset with at minimum hyperlinks to API endpoints, and MAY support content negotiation to also return their existing format.
Publishers SHOULD consider caching and compression techniques to reduce the network overhead of large API catalogs.
The API catalog MUST be named 'api-catalog' in a well-known location as described by RFC 8615. The /.well-known/api-catalog URI provides a convenient reference to that location.
The API catalog MUST include hyperlinks to API endpoints. It is RECOMMENDED that the catalog also include useful metadata such as usage policies, API version information, and links to OpenAPI Specification definitions.
The api-catalog URI SHALL be appended to the /.well-known/ path-prefix for well-known locations, and a /.well-known/api-catalog location MUST support the Linkset format application/linkset+json.
The Publisher MUST publish the API catalog document in the Linkset format application/linkset+json (RFC 9264 Section 4.2). The Linkset SHOULD include a profile parameter with value 'https://www.rfc-editor.org/info/rfc9727' to indicate it represents an API catalog.
An API catalog may contain links to other API catalogs by using the 'api-catalog' relation type for each link, enabling hierarchical grouping of large API portfolios across nested catalogs.
The 'api-catalog' link relation identifies a target resource that represents a list of APIs available from the Publisher of the link context. The target resource URI may be /.well-known/api-catalog or any other URI chosen by the Publisher.
The 'api-catalog' well-known URI is defined for HTTPS servers that publish APIs. A request to /.well-known/api-catalog returns an API catalog document describing the Publisher's API endpoints.
When used in an API catalog document, the 'item' link relation (RFC 6573) identifies a target resource that represents an API that is a member of the catalog. Other link relations (e.g., service-desc, service-doc, service-meta, status from RFC 8631) may convey metadata.
This specification registers 'https://www.rfc-editor.org/info/rfc9727' in the IANA 'Profile URIs' registry (per RFC 7284), with common name 'API catalog', to request or signal a Linkset representing an API catalog.
This specification registers the 'api-catalog' link relation in the IANA 'Link Relation Types' registry (per RFC 8288 Section 2.1.1.1), described as referring to a list of APIs available from the Publisher of the link context.
This specification registers the 'api-catalog' well-known URI in the IANA 'Well-Known URIs' registry with permanent status, as defined by RFC 8615.
A regularly audited API catalog may help decommission 'zombie' APIs — legacy or obsolete APIs that are unlikely to be supported, monitored, patched, or updated and therefore represent a security vulnerability.
For internal/private API scenarios, appropriate controls such as CORS policies and access control lists SHOULD be in place to ensure only authorised roles and systems may access an internal api-catalog well-known URI.
Rate-limiting measures are RECOMMENDED to help mitigate abuse and prevent denial-of-service attacks on the API catalog endpoint.
Security teams SHOULD audit the API catalog to ensure no APIs intended solely for internal use have been mistakenly included in a public-facing catalog, and should avoid exposing metadata about internal domains.
The Publisher SHOULD enforce read-only privileges for external requests to .well-known/api-catalog and for internal monitoring roles. Write privileges SHOULD only be granted to roles that perform updates to the API catalog.
The Publisher SHOULD perform a security and privacy review of the API catalog prior to deployment to ensure it does not leak personal, business, or other sensitive metadata, nor expose any vulnerability related to the listed APIs.
TLS SHOULD be used — i.e., /.well-known/api-catalog should be available exclusively over HTTPS — to ensure no tampering of the API catalog. Publishers SHOULD also follow the security considerations from RFC 8615 Section 4.