O cabeçalho Link e os tipos de relação de link

O que é

A RFC 8288 modela um link como um contexto, um tipo de relação, um destino e atributos opcionais do destino. Em um cabeçalho, ele é serializado assim:

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

Regras da RFC: vários links são separados por vírgula; rel é obrigatório e só a primeira ocorrência conta, mas um único valor de rel pode listar vários tipos de relação separados por espaços; rev está obsoleto. Os nomes de relação registrados são tokens em minúsculas, comparados sem diferenciar maiúsculas de minúsculas; qualquer nome não registrado deve ser uma URI absoluta, entre aspas se contiver ; ou ,. Destinos relativos são resolvidos em relação à URI da requisição, nunca em relação a um <base> presente no corpo. O contexto é, por padrão, o recurso requisitado; anchor o desloca para um fragmento ou outra URI. hreflang, media, title, title* e type são dicas sobre o destino. O registro da IANA lista os nomes registrados, entre eles alternate, canonical, describedby, next, prev, first, last, self, license, service-desc, service-doc, deprecation, sunset, preload e preconnect. A RFC 8297 define a resposta 103 Early Hints, cuja finalidade é enviar cabeçalhos Link antes da resposta final, para que o cliente possa começar a buscar recursos.

Por que importa

JSON, PDFs, imagens e Markdown não têm o elemento <link>. O cabeçalho dá a esses formatos links canonical, alternate e de paginação, que agentes, crawlers e clientes genéricos conseguem ler sem analisar o corpo, e mantém a lógica de paginação independente do formato do payload.

Como aplicar

• Pagine com rel="next" (e prev, first, last quando for barato); omita next na última página, para que a navegação do cliente termine.
• Aponte alternativas legíveis por máquina com rel="alternate"; type="text/markdown", a descrição da API com rel="service-desc" e a documentação para pessoas com rel="service-doc".
• Use rel="canonical" em representações que não sejam HTML, e rel="deprecation" e rel="sunset" junto com os respectivos cabeçalhos.
• Envie dicas de busca antecipada como Link: </app.css>; rel="preload"; as="style"; as é um parâmetro definido pelo HTML, transportado como extensão.
• Use uma biblioteca para o parsing: os valores podem estar divididos em vários campos Link, o que equivale a um único campo unido por vírgulas.

Armadilhas

Aspas: uma URI de extensão com ponto e vírgula quebra os parsers se não estiver entre aspas. Um link em uma resposta de erro, como um 404, tem um contexto anônimo. Muitos links inflam os cabeçalhos além dos limites dos proxies; reserve o cabeçalho para navegação e coloque conjuntos grandes de links no corpo.