link-headers 1.0.0

Link Headers Check v1.0.0

Status

• Version: 1.0.0
• Check identifier: link-headers
• Input contract: [email protected]
• Output contract: [email protected]
• Scope: homepage response headers plus advertised same-origin targets

Abstract

This check validates whether the homepage response exposes useful RFC 8288 Link headers for agent discovery and whether same-origin linked targets are reachable. Version 1.0.0 recognizes api-catalog, service-doc, service-desc, and service-meta as registered discovery relations. It also recognizes selected community conventions as weaker evidence.

Motivation

HTTP Link headers let clients discover machine-readable resources before parsing HTML. For agents, they can advertise API catalogs, service descriptions, and service documentation from the initial response in a standardized way.

Normative Model

RFC 8288 defines the Link header field as a way to express typed links between resources. Each link has a target URI reference and parameters such as rel and type. Registered relation types are maintained by IANA. RFC 9727 registers api-catalog for API catalog discovery, and RFC 8631 registers service-doc, service-desc, and service-meta for web service discovery.

This check treats each parsed Link value independently. Relative target references are resolved against the scanned origin. Registered relation values are compared case-insensitively and may contain multiple space-separated relation types. Same-origin targets are fetched; external targets are recorded but not fetched.

RFC 9264 defines linkset documents as a way to publish links outside response headers. application/linkset+json is therefore the preferred target media type for api-catalog when the catalog is expressed as a linkset.

Applicability

The check applies to every scanned homepage response. It uses the link header from website.homepage.headers.

The target validation step applies only to useful same-origin links. If all useful links point off origin, the check records that they were skipped and fails target validation because it cannot verify a reachable local discovery resource.

Pass Criteria

The check passes when both conditions are met:

• The homepage response contains at least one useful Link header whose rel value includes api-catalog, service-doc, service-desc, or service-meta.
• At least one useful same-origin target is fetched, every fetched target returns HTTP 2xx or 3xx, and each advertised type parameter matches or is compatible with the response Content-Type.

The check returns a warning when the only useful discovery relations are non-standard or community conventions such as rel="api" or the Hydra API documentation relation, even when the target is reachable.

Evidence Model

The result includes step evidence:

• Parsed Link header entries.
• Standard and community discovery relation tokens.
• Useful relation types found.
• Same-origin target fetch attempts.
• External targets skipped.
• Target status codes.
• Target response content types.
• Type match booleans.
• Target validation failures.

The result does not log or store response bodies from linked targets.

Validation/Scoring Steps

1. presence, weight 0.45: parse homepage Link headers and find useful relation types.
2. target-validation, weight 0.55: fetch same-origin useful targets and validate status plus advertised media type.

Standard Behavior

The parser accepts standard comma-separated Link header values and quoted parameters. Relative URI references are allowed and resolved against the scanned origin for fetch decisions. A single rel value can establish multiple links when it contains multiple space-separated relation types.

The type parameter is checked against the target response Content-Type. Exact containment is accepted, and this version also accepts:

• application/vnd.oai.openapi+json advertised with application/json.
• application/linkset+json advertised with application/linkset+json.
• text/markdown advertised with Markdown-like or text/plain responses.

Non-Standard And Real-World Behavior

Common production Link headers are often unrelated to API discovery: pagination (next, prev, first, last), performance hints (preload, preconnect), canonical links, and alternate representations are widely deployed. This check records parsed links as evidence but does not treat those relation types as passing discovery evidence.

Many sites advertise OpenAPI descriptions with vendor media types while serving generic application/json; this version treats that as compatible. Markdown resources are also often served as text/plain, so text/markdown accepts plain text when the target otherwise resolves.

Older API-discovery ecosystems use community relation conventions. APIs.json has used rel="api" for API description discovery, and Hydra uses the URI relation http://www.w3.org/ns/hydra/core#apiDocumentation to point to API documentation. Version 1.0.0 recognizes these as useful but weaker discovery evidence because they are not IANA-registered link relation tokens for this purpose.

External targets may be valid in production, especially for centralized developer portals. Version 1.0.0 records them but avoids fetching them to keep the check page-scoped and avoid unexpected third-party requests.

The registered status relation from RFC 8631 can point to service status information. This version does not treat status alone as sufficient agent discovery evidence because it does not describe how to use or document the API/service.

Non-Goals And Limitations

This version does not crawl linked resources recursively, parse API catalog contents, validate OpenAPI syntax, verify documentation quality, or fetch external targets. It does not infer useful discovery links from HTML <link> elements; that belongs to checks that explicitly inspect HTML discovery surfaces.

References

• www.rfc-editor.org/rfc/rfc8288
• www.rfc-editor.org/rfc/rfc8631
• www.rfc-editor.org/rfc/rfc9727#section-3
• www.rfc-editor.org/rfc/rfc9264
• www.iana.org/assignments/link-relations/link-relations.xhtml
• apisjson.org/format/apisjson_0.19.txt
• www.hydra-cg.com/spec/latest/core
• www.w3.org/ns/hydra/core#apiDocumentation
• developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link
• docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api

link-headers v1.0.0 Changelog

Initial versioned package for link-headers.

• Owns runtime behavior, metadata, references, scoring steps, input contract, output contract, docs, changelog, and remediation skill path in the versioned package.
• Adds version-aware runtime logging through runVersionedCheckWithLogging.
• Keeps legacy exports as thin compatibility wrappers that delegate to the versioned package.
• Documents and implements selected real-world/community discovery conventions as weaker evidence.