polyfill-service/docs/api.html

A polyfill combinator

{{>header}}

{{>nav}}

		<div class="o-techdocs-main o-techdocs-content">

			<h1>API reference</h1>

			<h2>Migrating from v1</h2>

			<aside>Here we're talking about the API version shown in the path (eg. <code>/v1/polyfill.min.js</code>), not the project version you find in the package.json file.</aside>

			<ul>
				<li><code>libVersion</code> is no longer supported.  We no longer support using an older version of the polyfill collection with the current version of the service.  To use an older polyfill library, use the version of the project that contains the library in the state you want it (not possible if using cdn.polyfill.io)</li>
				<li><code>gated</code> is no longer supported.  Use <code>flags</code> instead.</li>
				<li>There are changes to the Node API.  See the README for details.</li>
			</ul>

			<h2>GET /v{{apiversion}}/polyfill<var>:minify</var>.<var>:type</var></h2>

			<p>Fetch a polyfill bundle.</p>

			<table class='apidoc'>
				<tr>
					<th>Param</th><th>Where</th><th>Description</th>
				</tr><tr>
					<td><code>minify</code></td>
					<td>URL</td>
					<td>
						Whether to minify the result.  If omitted, output will include the full polyfill source, and a header comment with debug information about the user agent and which polyfills have been included in the bundle.  If set to <code>.min</code>, the output will be minified.
					</td>
				</tr><tr>
					<td><code>type</code></td>
					<td>URL</td>
					<td>
						Set to <code>js</code>.  Currently we only support JavaScript polyfills, but the <code>css</code> type is reserved for future use.
					</td>
				</tr><tr>
					<td><code>features</code></td>
					<td>Querystring</td>
					<td>
						<p>List of browser features to polyfill. Accepts a comma-separated list of feature names.  Available feature names are shown on the <a href='/v{{apiversion}}/docs/features/'>Browsers and Features</a> page, though group aliases such as 'es5' and 'es6' are also accepted (these are defined in the polyfills' config.json files - <a href="https://github.com/Financial-Times/polyfill-service/blob/master/polyfills/Array/from/config.json">here's an example</a>).</p>
						<p>Each feature name may optionally be appended with zero or more of the following flags:</p>
						<dl>
							<dt><code>|always</code></dt>
							<dd>Polyfill should be included regardless of whether it is required by the user-agent making the request.  If there are multiple browser-specific variants of the polyfill, the default one will be used for browser that doesn't actually require the polyfill.  In some cases where the only way of implementing a polyfill is to use browser-specific proprietary technology, the default variant may be empty.</dd>
							<dt><code>|gated</code></dt>
							<dd>If the polyfill is included in the bundle, it will be accompanied by a feature detect, which will only execute the polyfill if the native API is not present.</dd>
						</dl>
						<p>Omitting or setting to an empty string is equivalent to the value "default", which is an alias for a curated list of the most popular polyfills.  Setting the value "all" will select every feature in the library (this is an extremely bad idea)</p>
					</td>
				</tr><tr>
					<td><code>excludes</code></td>
					<td>Querystring</td>
					<td>
						<p>List of browser features to exclude from output. Accepts a comma-separated list of feature names.  Available feature names are shown on the <a href='/v{{apiversion}}/docs/features/'>Browsers and Features</a> page.  Aliases and flags are not accepted. Omitting or setting to an empty string will exclude no polyfills.</p>
						<p>The main use case for this is where you want a polyfill but you don't want one or more of its dependencies.  Note that it doesn't make any sense to list the same feature in both the <code>features</code> and the <code>excludes</code> list.
					</td>
				</tr><tr>
					<td><code>flags</code></td>
					<td>Querystring</td>
					<td><p>Comma separated list of flags to apply to <strong>all</strong> features.  For available options see the list in the <code>features</code> parameter documented above.  Equivalent to adding <code>|<em>flagname</em></code> to every feature in the <code>features</code> argument.</p><p>For example, <code>&amp;flags=always,gated</code> will apply both the <code>always</code> and the <code>gated</code> flag to all features requested in the <code>features</code> parameter.</td>
				</tr><tr>
					<td><code>ua</code></td>
					<td>Querystring</td>
					<td>
						<p>User agent string to override the <code>User-Agent</code> header on the request.  Useful if the polyfill service is being used from the server-side, and in that scenario, this is preferable to setting an inaccurate <code>User-Agent</code> header (the User-Agent header should properly be set to a string identifying the client you are using to make the request - for server side requests that might be cURL, for example).</p>
						<p>Normally, responses from the service will Vary on User-Agent. Setting the <code>ua</code> parameter means responses no longer differ between user agents, so the <code>Vary</code> header will not list User-Agent as a vary value.</p>
					</td>
				</tr><tr>
					<td><code>callback</code></td>
					<td>Querystring</td>
					<td>Name of JavaScript function to call after polyfills are loaded.  Must match the PCRE expression <code>^[\w\.]+$</code> otherwise will have no effect.  Note that this feature differs from normal JSONp in that nothing is passed to the function - it is simply a way of triggering your own code when the polyfills have loaded, intended to allow the polyfill service to be more easily loaded asynchronously with <code>async</code> and <code>defer</code> attributes.</td>
				</tr>
				<tr>
					<td><code>unknown</code></td>
					<td>Querystring</td>
					<td>What to do when the user agent is not recognised.  Set to `polyfill` to return default polyfill variants of all qualifying features, `ignore` to return nothing.  Use caution when setting this argument to 'polyfill' on large feature sets, since huge polyfill bundles may cause crashes or lockups in extremely old or underpowered user agents.  Defaults to `ignore`.</td>
				</tr>
			</table>
		</div>

{{>footer}}