283 lines
8.4 KiB
Markdown
283 lines
8.4 KiB
Markdown
# window.fetch polyfill
|
|
|
|
The `fetch()` function is a Promise-based mechanism for programmatically making
|
|
web requests in the browser. This project is a polyfill that implements a subset
|
|
of the standard [Fetch specification][], enough to make `fetch` a viable
|
|
replacement for most uses of XMLHttpRequest in traditional web applications.
|
|
|
|
This project adheres to the [Open Code of Conduct][]. By participating, you are
|
|
expected to uphold this code.
|
|
|
|
## Table of Contents
|
|
|
|
* [Read this first](#read-this-first)
|
|
* [Installation](#installation)
|
|
* [Usage](#usage)
|
|
* [HTML](#html)
|
|
* [JSON](#json)
|
|
* [Response metadata](#response-metadata)
|
|
* [Post form](#post-form)
|
|
* [Post JSON](#post-json)
|
|
* [File upload](#file-upload)
|
|
* [Caveats](#caveats)
|
|
* [Handling HTTP error statuses](#handling-http-error-statuses)
|
|
* [Sending cookies](#sending-cookies)
|
|
* [Receiving cookies](#receiving-cookies)
|
|
* [Obtaining the Response URL](#obtaining-the-response-url)
|
|
* [Browser Support](#browser-support)
|
|
|
|
## Read this first
|
|
|
|
* If you believe you found a bug with how `fetch` behaves in Chrome or Firefox,
|
|
please **avoid opening an issue in this repository**. This project is a
|
|
_polyfill_, and since Chrome and Firefox both implement the `window.fetch`
|
|
function natively, no code from this project actually takes any effect in
|
|
these browsers. See [Browser support](#browser-support) for detailed
|
|
information.
|
|
|
|
* If you have trouble **making a request to another domain** (a different
|
|
subdomain or port number also constitutes as another domain), please
|
|
familiarize yourself with all the intricacies and limitations of [CORS][]
|
|
requests. Because CORS requires participation of the server by implementing
|
|
specific HTTP response headers, it is often nontrivial to set up or debug.
|
|
CORS is exclusively handled by the browser's internal mechanisms which this
|
|
polyfill cannot influence.
|
|
|
|
* If you have trouble **maintaining the user's session** or [CSRF][] protection
|
|
through `fetch` requests, please ensure that you've read and understood the
|
|
[Sending cookies](#sending-cookies) section.
|
|
|
|
* If this polyfill **doesn't work under Node.js environments**, that is expected,
|
|
because this project is meant for web browsers only. You should ensure that your
|
|
application doesn't try to package and run this on the server.
|
|
|
|
* If you have an idea for a new feature of `fetch`, please understand that we
|
|
are only ever going to add features and APIs that are a part of the
|
|
[Fetch specification][]. You should **submit your feature requests** to the
|
|
[repository of the specification](https://github.com/whatwg/fetch/issues)
|
|
itself, rather than this repository.
|
|
|
|
## Installation
|
|
|
|
* `npm install whatwg-fetch --save`; or
|
|
|
|
* `bower install fetch`.
|
|
|
|
You will also need a Promise polyfill for [older browsers](http://caniuse.com/#feat=promises).
|
|
We recommend [taylorhakes/promise-polyfill](https://github.com/taylorhakes/promise-polyfill)
|
|
for its small size and Promises/A+ compatibility.
|
|
|
|
For use with webpack, add this package in the `entry` configuration option
|
|
before your application entry point:
|
|
|
|
```javascript
|
|
entry: ['whatwg-fetch', ...]
|
|
```
|
|
|
|
For Babel and ES2015+, make sure to import the file:
|
|
|
|
```javascript
|
|
import 'whatwg-fetch'
|
|
```
|
|
|
|
## Usage
|
|
|
|
For a more comprehensive API reference that this polyfill supports, refer to
|
|
https://github.github.io/fetch/.
|
|
|
|
### HTML
|
|
|
|
```javascript
|
|
fetch('/users.html')
|
|
.then(function(response) {
|
|
return response.text()
|
|
}).then(function(body) {
|
|
document.body.innerHTML = body
|
|
})
|
|
```
|
|
|
|
### JSON
|
|
|
|
```javascript
|
|
fetch('/users.json')
|
|
.then(function(response) {
|
|
return response.json()
|
|
}).then(function(json) {
|
|
console.log('parsed json', json)
|
|
}).catch(function(ex) {
|
|
console.log('parsing failed', ex)
|
|
})
|
|
```
|
|
|
|
### Response metadata
|
|
|
|
```javascript
|
|
fetch('/users.json').then(function(response) {
|
|
console.log(response.headers.get('Content-Type'))
|
|
console.log(response.headers.get('Date'))
|
|
console.log(response.status)
|
|
console.log(response.statusText)
|
|
})
|
|
```
|
|
|
|
### Post form
|
|
|
|
```javascript
|
|
var form = document.querySelector('form')
|
|
|
|
fetch('/users', {
|
|
method: 'POST',
|
|
body: new FormData(form)
|
|
})
|
|
```
|
|
|
|
### Post JSON
|
|
|
|
```javascript
|
|
fetch('/users', {
|
|
method: 'POST',
|
|
headers: {
|
|
'Content-Type': 'application/json'
|
|
},
|
|
body: JSON.stringify({
|
|
name: 'Hubot',
|
|
login: 'hubot',
|
|
})
|
|
})
|
|
```
|
|
|
|
### File upload
|
|
|
|
```javascript
|
|
var input = document.querySelector('input[type="file"]')
|
|
|
|
var data = new FormData()
|
|
data.append('file', input.files[0])
|
|
data.append('user', 'hubot')
|
|
|
|
fetch('/avatars', {
|
|
method: 'POST',
|
|
body: data
|
|
})
|
|
```
|
|
|
|
### Caveats
|
|
|
|
The `fetch` specification differs from `jQuery.ajax()` in mainly two ways that
|
|
bear keeping in mind:
|
|
|
|
* The Promise returned from `fetch()` **won't reject on HTTP error status**
|
|
even if the response is an HTTP 404 or 500. Instead, it will resolve normally,
|
|
and it will only reject on network failure or if anything prevented the
|
|
request from completing.
|
|
|
|
* By default, `fetch` **won't send or receive any cookies** from the server,
|
|
resulting in unauthenticated requests if the site relies on maintaining a user
|
|
session. See [Sending cookies](#sending-cookies) for how to opt into cookie
|
|
handling.
|
|
|
|
#### Handling HTTP error statuses
|
|
|
|
To have `fetch` Promise reject on HTTP error statuses, i.e. on any non-2xx
|
|
status, define a custom response handler:
|
|
|
|
```javascript
|
|
function checkStatus(response) {
|
|
if (response.status >= 200 && response.status < 300) {
|
|
return response
|
|
} else {
|
|
var error = new Error(response.statusText)
|
|
error.response = response
|
|
throw error
|
|
}
|
|
}
|
|
|
|
function parseJSON(response) {
|
|
return response.json()
|
|
}
|
|
|
|
fetch('/users')
|
|
.then(checkStatus)
|
|
.then(parseJSON)
|
|
.then(function(data) {
|
|
console.log('request succeeded with JSON response', data)
|
|
}).catch(function(error) {
|
|
console.log('request failed', error)
|
|
})
|
|
```
|
|
|
|
#### Sending cookies
|
|
|
|
To automatically send cookies for the current domain, the `credentials` option
|
|
must be provided:
|
|
|
|
```javascript
|
|
fetch('/users', {
|
|
credentials: 'same-origin'
|
|
})
|
|
```
|
|
|
|
The "same-origin" value makes `fetch` behave similarly to XMLHttpRequest with
|
|
regards to cookies. Otherwise, cookies won't get sent, resulting in these
|
|
requests not preserving the authentication session.
|
|
|
|
For [CORS][] requests, use the "include" value to allow sending credentials to
|
|
other domains:
|
|
|
|
```javascript
|
|
fetch('https://example.com:1234/users', {
|
|
credentials: 'include'
|
|
})
|
|
```
|
|
|
|
#### Receiving cookies
|
|
|
|
As with XMLHttpRequest, the `Set-Cookie` response header returned from the
|
|
server is a [forbidden header name][] and therefore can't be programmatically
|
|
read with `response.headers.get()`. Instead, it's the browser's responsibility
|
|
to handle new cookies being set (if applicable to the current URL). Unless they
|
|
are HTTP-only, new cookies will be available through `document.cookie`.
|
|
|
|
Bear in mind that the default behavior of `fetch` is to ignore the `Set-Cookie`
|
|
header completely. To opt into accepting cookies from the server, you must use
|
|
the `credentials` option.
|
|
|
|
#### Obtaining the Response URL
|
|
|
|
Due to limitations of XMLHttpRequest, the `response.url` value might not be
|
|
reliable after HTTP redirects on older browsers.
|
|
|
|
The solution is to configure the server to set the response HTTP header
|
|
`X-Request-URL` to the current URL after any redirect that might have happened.
|
|
It should be safe to set it unconditionally.
|
|
|
|
``` ruby
|
|
# Ruby on Rails controller example
|
|
response.headers['X-Request-URL'] = request.url
|
|
```
|
|
|
|
This server workaround is necessary if you need reliable `response.url` in
|
|
Firefox < 32, Chrome < 37, Safari, or IE.
|
|
|
|
## Browser Support
|
|
|
|
- Chrome
|
|
- Firefox
|
|
- Safari 6.1+
|
|
- Internet Explorer 10+
|
|
|
|
Note: modern browsers such as Chrome, Firefox, and Microsoft Edge contain native
|
|
implementations of `window.fetch`, therefore the code from this polyfill doesn't
|
|
have any effect on those browsers. If you believe you've encountered an error
|
|
with how `window.fetch` is implemented in any of these browsers, you should file
|
|
an issue with that browser vendor instead of this project.
|
|
|
|
|
|
[fetch specification]: https://fetch.spec.whatwg.org
|
|
[open code of conduct]: http://todogroup.org/opencodeofconduct/#fetch/opensource@github.com
|
|
[cors]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS
|
|
"Cross-origin resource sharing"
|
|
[csrf]: https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)_Prevention_Cheat_Sheet
|
|
"Cross-site request forgery"
|
|
[forbidden header name]: https://developer.mozilla.org/en-US/docs/Glossary/Forbidden_header_name
|