whatwg-fetch

What is whatwg-fetch?

The whatwg-fetch npm package is a polyfill for the Fetch API, a modern interface for making network requests in browsers and Node.js. It allows developers to make HTTP requests to retrieve or send data to remote servers in an easy and efficient way. The Fetch API provides a more powerful and flexible feature set compared to older technologies like XMLHttpRequest.

What are whatwg-fetch's main functionalities?

Making GET requests

This code sample demonstrates how to make a GET request to retrieve data from a specified URL and then process the response as JSON.

fetch('https://api.example.com/data')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Making POST requests

This code sample shows how to make a POST request to send JSON data to a server and then handle the JSON response.

fetch('https://api.example.com/data', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ key: 'value' })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Handling HTTP errors

This code sample illustrates how to handle HTTP errors by checking the response status before processing the response.

fetch('https://api.example.com/data')
  .then(response => {
    if (!response.ok) {
      throw new Error('Network response was not ok');
    }
    return response.json();
  })
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Other packages similar to whatwg-fetch

axios

Axios is a popular HTTP client for the browser and Node.js. It provides a promise-based API and has a similar feature set to whatwg-fetch, including interceptors, automatic transforms for JSON data, and cancellation. Axios is often preferred for its more convenient error handling and wider browser support without polyfills.

node-fetch

node-fetch is a light-weight module that brings the Fetch API to Node.js. It is similar to whatwg-fetch but is specifically designed for Node.js environments. It provides a simple interface for making HTTP requests and is a drop-in replacement for native fetch in Node.js.

ky

Ky is a tiny and elegant HTTP client based on the Fetch API. It extends the capabilities of fetch with additional features like retrying failed requests, timeout handling, and more convenient methods for parsing responses. Ky is designed to offer a more developer-friendly API compared to whatwg-fetch.

README

window.fetch polyfill

The global fetch function is an easier way to make web requests and handle responses than using an XMLHttpRequest. This polyfill is written as closely as possible to the standard Fetch specification at https://fetch.spec.whatwg.org.

Installation

Available on Bower as fetch.

$ bower install fetch

You'll also need a Promise polyfill for older browsers.

$ bower install es6-promise

This can also be installed with npm.

$ npm install whatwg-fetch --save

(For a node.js implementation, try node-fetch)

Usage

The fetch function supports any HTTP method. We'll focus on GET and POST example requests.

HTML

fetch('/users.html')
  .then(function(response) {
    return response.text()
  }).then(function(body) {
    document.body.innerHTML = body
  })

JSON

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

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

var form = document.querySelector('form')

fetch('/query', {
  method: 'post',
  body: new FormData(form)
})

Post JSON

fetch('/users', {
  method: 'post',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Hubot',
    login: 'hubot',
  })
})

File upload

var input = document.querySelector('input[type="file"]')

var form = new FormData()
form.append('file', input.files[0])
form.append('user', 'hubot')

fetch('/avatars', {
  method: 'post',
  body: form
})

Success and error handlers

This causes fetch to behave like jQuery's $.ajax by rejecting the Promise on HTTP failure status codes like 404, 500, etc. The response Promise is resolved only on successful, 200 level, status codes.

function status(response) {
  if (response.status >= 200 && response.status < 300) {
    return response
  }
  throw new Error(response.statusText)
}

function json(response) {
  return response.json()
}

fetch('/users')
  .then(status)
  .then(json)
  .then(function(json) {
    console.log('request succeeded with json response', json)
  }).catch(function(error) {
    console.log('request failed', error)
  })

Response URL caveat

The Response object has a URL attribute for the final responded resource. Usually this is the same as the Request url, but in the case of a redirect, its all transparent. Newer versions of XHR include a responseURL attribute that returns this value. But not every browser supports this. The compromise requires setting a special server side header to tell the browser what URL it just requested (yeah, I know browsers).

response.headers['X-Request-URL'] = request.url

If you want response.url to be reliable, you'll want to set this header. The day that you ditch this polyfill and use native fetch only, you can remove the header hack.

Browser Support

Latest ✔	Latest ✔	9+ ✔	Latest ✔	6.1+ ✔

Changelog

v0.8.1

4 May 2015

• Fetch 0.8.1 09c316d
• Ignore script/ dir 2e39db1