Link

The HTTP Link header is used to serialize HTTP links into a HTTP header field.

Usage

The HTTP Link header provides a means for link serialization in HTTP headers. It is semantically equivalent to using an HTML <link> element.

The only required directive is the URI, which must be included between the < and > symbols. Each URI can also be accompanied by relevant parameters. Parameters are delimited using a semicolon ;, as follows:

Link: <URI>; parameter1=value1; parameter2="value2"

Some of the more commonly used parameters of the rel attribute are listed below.

preconnect

The preconnect parameter is part of the resource hints framework and is used to indicate resources that can be more quickly served if an early connection is initiated. The connection includes a DNS lookup, TCP handshake, and optionally TLS negotiation. Connecting early has the benefit of masking the latency required to fetch the resources.

Initiating a preconnect requires the following steps:

• Resolve the URL and obtain the absolute URL. If it is not of scheme “http" or “https" then the connection cannot be completed.
• Make the connection.
• Set the corsAttributeState to be the current state of the element’s crossorigin attribute.
• Set the credentials attribute to boolean true.
• If the corsAttributeState is anonymous and the origin is not equal to the current document’s origin then set the credentials attribute to boolean false.
• Obtain the connection with the origin and credentials.

Importantly, for any of the resource hints parameters, the user agent cannot delay loading the actual document because it is waiting for outstanding preconnect requests to be completed. The specifics about when to best load resources are left up to the client.

Example

Response

Link: <https://example.re>; rel="preconnect"
Link: <https://www.example.re>; rel="preconnect"; crossorigin

dns-prefetch

The dns-prefetch parameter is also part of the resource hints framework. It is sent by the server to specify an origin that will be used to fetch resources to fulfill the request. The client is expected to perform DNS resolution as soon as possible.

Example

Response

Link: <https://example.re>; rel="preconnect"
Link: <https://example.re>; rel="dns-prefetch"

prefetch

The prefetch parameter is another option that makes up the resource hints framework. It indicates resources that may be required by the next user action, and as such, shall be fetched so that the resource can be more quickly fetched.

For resources that have been prefetched, the user is not allowed to apply to preprocess, or automatically execute or apply it against the content within the current page.

The as attribute is optional and must adhere to the requirements defined by PRELOAD, as specified by the resource hints framework.

The crossorigin CORS attribute is optional and is used to specify the CORS policy adopted by the resource.

Example

Response

Link: <https://example.re/library.js>; rel="prefetch"; crossorigin="use-credentials"; as="script"

prerender

The prerender parameter is part of the resource hints framework and is used to identify resources that can be used by the next user action, which shall be fetched and executed. This allows the user agent to deliver a faster response when the resource is actually requested.

The choice of whether to preprocess the HTML response is left to the client. As such, the client has several options for handling the request in the prerender stage, as follows:

• Some requests may be delayed until the resource is made visible, such as media downloads.
• If the client’s resources are limited then it can prevent prerendering from being initiated, or instead, reduce the allocation of CPU cycles, GPU cycles, or memory allocated to the task.
• Prerendering can be delayed due to the high cost of resource requirements, such as the requirement for expensive data access.
• Depending on the properties of the fetched resource, prerendering may be abandoned. For example, if the target resource exhibits non-idempotent behavior, or it triggers a condition that requires user input.

Generally, the prefetched resources are stored according to their respective Caching headers, except when no-store is present in the Cache-Control header. In addition, resources may be re-validated before use if there is a Vary header, no-cache in the Cache-Control header or if the resource is more than 5 minutes old.

To make HTTP requests due to prerender mechanisms distinguishable from normal browsing, browsers may add the HTTP Purpose header to the HTTP request.

Example

Response

Link: <https://example.re/next-page>; rel="prerender"

preload

The preload parameter is used to create an external resource link and can be used to achieve a server push. The client will fetch and cache the target resource according to the possible destination, direct by the as attribute. It will also consider the priority associated with the destination.

As with the other speculative fetch commands, the loading of the resource cannot be delayed pending the outcome of this action. Fetching the resource is best done at the following times:

• When the external resource’s link element is or comes browsing-context connected.
• When there is a change to the href element for a link that is already browsing-context connected.
• When there is a change to the type attribute that was not previously obtained (e.g. because it was an unsupported type).
• When the media attribute is changed but had not previously been obtained (e.h. it has not matched the environment).

Example

Response

Link: <https://example.re/short-video.mp4>; rel="preload"; as="video"; type="video/mp4"

canonical

The canonical parameter is used to indicate that the URL is pointing to the primary version of the content. This is beneficial in cases where a site contains several versions of the same content but they have different URLs. Some of the most common reasons for this are:

• Support for multiple device types may have different URLs, such as:
  • https://www.example.re is optimized for desktops
  • https://m.example.re is optimized for mobile devices
• Dynamic URLs are frequently used for searching for and highlighting keywords or sections
  • https://www.example.re/search?q=training
  • https://www.example.re/search
• The same content is available at multiple URLs
  • https://www.example.re/
  • https://www.example.re/?utm_source=ad-campaign

When multiple URLs are available for the same content, search engines such as Googlebot will mark one of the URLs as the canonical. Search engines will then use these canonicals to optimize crawling and indexation by grouping its signals to the assigned canonical.

Example

Response

Link: <https://example.re/>; rel="canonical"

hreflang attribute

The hreflang attribute is used, in combination with rel="alternate", to indicate alternate language and region variants for the content on a page.

Example

In this example, the URLs point to three different versions of the same content. The first URL points to the American English version on the "us" subdomain, whereas the second URL point to the British English version of the content on the "uk" subdomain. The third URL is declared as a general catch-all for any user outside the two declared locales to go a general landing page on the "www" subdomain, which often contains a language and/or country choice and/or an alternate language version of the content not targeted to the specific countries.

Response

Link: <https://us.example.re/>; rel="alternate"; hreflang="en-US",
         <https://uk.example.re/>; rel="alternate"; hreflang="en-GB",
         <https://www.example.re/>; rel="alternate"; hreflang="x-default"

Takeaway

The HTTP Link header provides a mechanism for HTTP link serialization in headers. This can help in a variety of ways including optimizing retrieval time using the resource hints framework, or pointing out duplicates for indexers so that they can avoid unnecessary crawling.

See also

• HTTP headers
• Resource Hints