Skip to content

DISC-010Find

Agent discovery Link headers on the home page

Whether your home page's HTTP Link header points agents to machine-readable descriptions of your shop.

What we check

We read the Link response header on your home page (RFC 8288, Web Linking) and look for relations that lead to a machine-readable description of the shop: api-catalog (RFC 9727), service-desc, service-doc, service-meta, describedby, linkset and ard. A rel="alternate" link counts only when its type is text/markdown, application/json, application/ld+json or application/linkset+json. An RSS feed alternate does not count, so we are stricter here than some other checkers.

Why it matters

An agent that visits your home page sees its response headers before it reads any content. A Link header that names your API catalogue, API description or Markdown version tells the agent where to find structured information without guessing URLs, so it can reach your products and services more directly.

How we check

We send no extra request. We read the headers of the home page our crawl already captured. We parse every Link entry, including several links in one header and several rel values in one link, and compare rel values without regard to case. PASS: at least one link uses one of the relations listed above, or a qualifying alternate. FAIL: there is no Link header, or it holds only other relations. Shopify, for example, currently sends only performance hints such as preconnect and preload, which do not count. The evidence lists the rel values we saw. SKIPPED: the crawl captured no home page, or bot management answered instead of your shop, so the headers were not yours.

How to fix it

  1. Add a Link response header to your home page that points to machine-readable descriptions of the shop, for example: Link: </.well-known/api-catalog>; rel="api-catalog", </openapi.json>; rel="service-desc".
  2. If you serve a Markdown version of the page, announce it too: Link: </index.md>; rel="alternate"; type="text/markdown".
  3. Point each link only at a document that really exists. A link to a missing page gives an agent nothing.
  4. On hosted platforms where you cannot set response headers, this usually needs a CDN or edge rule in front of the store. Check what your platform allows.

What good looks like

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Link: </.well-known/api-catalog>; rel="api-catalog",
      </openapi.json>; rel="service-desc"; type="application/json",
      </index.md>; rel="alternate"; type="text/markdown"

Sources