The Link header and link relation types

What it is

RFC 8288 models a link as a context, a relation type, a target and optional target attributes. In a header it is serialised as:

Link: </orders?cursor=abc>; rel="next",
      </openapi.json>; rel="service-desc"; type="application/json",
      </docs/orders>; rel="service-doc"

Rules from the RFC: several links are comma-separated; rel is required and only its first occurrence counts, but one rel value may list several relation types separated by spaces; rev is deprecated. Registered relation names are lowercase tokens compared case-insensitively; anything unregistered must be an absolute URI and quoted if it contains ; or ,. Relative targets resolve against the request URI, never against a <base> in the body. The context defaults to the requested resource; anchor moves it to a fragment or another URI. hreflang, media, title, title* and type are hints about the target. The IANA registry lists the registered names, among them alternate, canonical, describedby, next, prev, first, last, self, license, service-desc, service-doc, deprecation, sunset, preload and preconnect. RFC 8297 defines the 103 Early Hints response, whose purpose is to send Link headers before the final response so a client can start fetching.

Why it matters

JSON, PDFs, images and Markdown have no <link> element. The header gives them canonical, alternate and pagination links that agents, crawlers and generic clients can read without parsing the body, and it keeps pagination logic independent of the payload format.

How to apply

• Paginate with rel="next" (and prev, first, last when cheap); omit next on the last page so a client walk terminates.
• Point machine-readable alternates at rel="alternate"; type="text/markdown", the API description at rel="service-desc", human documentation at rel="service-doc".
• Use rel="canonical" on non-HTML representations and rel="deprecation" and rel="sunset" alongside those headers.
• Send early-fetch hints as Link: </app.css>; rel="preload"; as="style"; as is a parameter defined by HTML, carried as an extension.
• Parse with a library: values may be split over several Link fields, which are equivalent to one comma-joined field.

Pitfalls

Quoting: an extension URI with a semicolon breaks parsers unless quoted. A link on an error response such as a 404 has an anonymous context. Many links inflate headers past proxy limits; keep the header for navigation and put large link sets in the body.