Requesting early arrival of special resources
This note describes how to use the HTTP 'link' request header to retrieve resources earlier, using HTTP/2 push.
The HTTP/2 push protocol allows multiple resources to be retrieved from the server with a single browser request. To make use of this, the requestor can include a special
link header with the request. This can be accomplished with
XMLHttpRequest or asynchronous
Use of this feature may, for example, improve the user experience for an embedded
<iframe>, where the request for a document and all its dependent resources are made in a single
Note that the HTML
<link> element is similar in purpose, but its usage is applied by the browser after the HTML document has been retrieved and parsed. Because of this, it is not truly a server push operation. The browser uses all of its normal fetching and caching algorithms and the server treats it as a normal HTTP request/response.
link request header, by specification, may take these attributes:
- The URL of the resource being requested, which must be delimited with an opening
<and a closing
rel=preloadattribute, which is required.
nopushattribute, which is optional.
asattribute, which identifies a generic resource type, but which is not used by the server.
crossoriginattribute, which is not used by the server.
mediaattribute, which is not used by the server.
The URL may be a fully specified URL (with protocol, hostname, port, and resource path) or it may be an absolute or relative resource path.
When the optional
nopush attribute is included in the link header, no push processing will occur.
The use of more than one
link request header is not supported. Only the last one will apply.
More than one resource may be requested in a single link header, by using a comma-separated concatenation of the resources. Each resource must redundantly include the
as attribute may be omitted. It is used by browser-initiated preloads only. The server instead relies on its configured
content-types to definitively assign a mime-type to the resource, and to send that mime-type in the
content-type response header.
push-priority module must be
on in the
module section for any of this to be effective.
Example 1: Link header with fully specified URL
link: <https://example.com/other/styles.css>; rel=preload
Example 2: Link header with absolute path
link: </styles.css>; rel=preload
Example 3: Link header with relative path
link: <../../styles.css>; rel=preload
Example 4: Link header for preloading multiple resources
link: <https://example.com/styles.css>; rel=preload, <https://example.com/ecmascript.js>; rel=preload, <https://example.com/neue.woff2>; rel=preload
Example 5: Explicit NOPUSH to disable preloading
link: <https://example.com/styles.css>; rel=preload; nopush
Key points to remember:
- The push-priority module must be on for preload-push to work.
- A single <link> request header is used to request multiple resources.