Skip to content

DISC-011Find

API catalog published

Whether your shop publishes an RFC 9727 API catalogue at /.well-known/api-catalog.

What we check

We check for an API catalogue at /.well-known/api-catalog as defined by RFC 9727 (June 2025, Standards Track). The catalogue is a Linkset document (RFC 9264). It must be served as application/linkset+json and must contain a non-empty "linkset" array, with one entry per API that links to its description and documentation.

Why it matters

If you offer public APIs, for example for your catalogue, cart or orders, an agent can use them to find products, check stock and prices, or look up an order without scraping pages. The well-known API catalogue is the standard place where an agent looks for which APIs exist and where their OpenAPI descriptions are. If you have no public APIs, there is nothing to list, and a FAIL here only records that no catalogue was found.

How we check

We make one request for /.well-known/api-catalog. PASS: the response parses as JSON, has a non-empty "linkset" array and is served as application/linkset+json. WARN: the body is not JSON, has no linkset entries (for example a CDN's JSON "not found" message sent with status 200), or is a valid linkset served under another media type such as application/json. FAIL: the path returns 404 or 410, or returns your site's ordinary HTML page, which is what storefronts that answer every URL return. SKIPPED: bot management answered instead of your shop, your robots.txt disallows the path for our crawler, or the server returned a status such as 429, a 5xx or an unexplained 403.

How to fix it

  1. If you have public APIs (catalogue, cart, orders), publish an RFC 9727 catalogue at /.well-known/api-catalog.
  2. Serve it as application/linkset+json (with profile="https://www.rfc-editor.org/info/rfc9727" if you can), containing a "linkset" array with one entry per API.
  3. In each entry, link to the API's service-desc (for example an OpenAPI file) and service-doc (human-readable documentation).
  4. Make the path answer HEAD requests as well, with a Link header of rel="api-catalog".
  5. If you have no public APIs, you do not need a catalogue.

What good looks like

GET /.well-known/api-catalog

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

{
  "linkset": [
    {
      "anchor": "https://example.com/api/catalog/v1",
      "service-desc": [
        { "href": "https://example.com/api/catalog/v1/openapi.json", "type": "application/json" }
      ],
      "service-doc": [
        { "href": "https://example.com/developers/catalog", "type": "text/html" }
      ]
    }
  ]
}

Sources