Docs
README
11.3 Fetch API and HTTP
Overview
The Fetch API provides a modern, Promise-based way to make HTTP requests in JavaScript. It's the successor to XMLHttpRequest (XHR) and offers a cleaner, more powerful interface.
┌──────────────────────────────────────────────────────────────────┐
│ Fetch API Flow │
├──────────────────────────────────────────────────────────────────┤
│ │
│ JavaScript Network Server │
│ ┌─────────┐ ┌───────┐ ┌─────────┐ │
│ │ │──fetch()──▶│ │──Request──▶│ │ │
│ │ Code │ │ HTTP │ │ API │ │
│ │ │◀─Promise──│ │◀─Response─│ │ │
│ └─────────┘ └───────┘ └─────────┘ │
│ │
│ fetch(url, options) │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Promise │ │
│ │ ┌───────────┐ │ │
│ │ │ Response │ │ → Headers, Status, Body │
│ │ └───────────┘ │ │
│ └─────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
HTTP Methods
| Method | Purpose | Has Body | Idempotent |
|---|---|---|---|
| GET | Retrieve data | No | Yes |
| POST | Create resource | Yes | No |
| PUT | Replace resource | Yes | Yes |
| PATCH | Partial update | Yes | No |
| DELETE | Remove resource | Optional | Yes |
| HEAD | Get headers only | No | Yes |
| OPTIONS | Check capabilities | No | Yes |
Basic Fetch Syntax
// GET request (default)
fetch('https://api.example.com/data')
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error(error));
// With async/await
async function getData() {
try {
const response = await fetch('https://api.example.com/data');
const data = await response.json();
return data;
} catch (error) {
console.error('Fetch failed:', error);
}
}
Fetch Options
┌─────────────────────────────────────────────────────────────────┐
│ Fetch Request Options │
├─────────────────────────────────────────────────────────────────┤
│ │
│ fetch(url, { │
│ method: 'POST', // HTTP method │
│ headers: { // Request headers │
│ 'Content-Type': 'application/json', │
│ 'Authorization': 'Bearer token123' │
│ }, │
│ body: JSON.stringify(data), // Request body │
│ mode: 'cors', // cors, no-cors, same-origin │
│ credentials: 'include', // include, same-origin, omit │
│ cache: 'no-cache', // Cache mode │
│ redirect: 'follow', // follow, error, manual │
│ signal: controller.signal // AbortController signal │
│ }) │
│ │
└─────────────────────────────────────────────────────────────────┘
Response Object
┌─────────────────────────────────────────────────────────────────┐
│ Response Object │
├─────────────────────────────────────────────────────────────────┤
│ │
│ response.ok │ Boolean: true if status 200-299 │
│ response.status │ HTTP status code (200, 404, etc.) │
│ response.statusText │ Status message ("OK", "Not Found") │
│ response.headers │ Headers object │
│ response.url │ Final URL after redirects │
│ response.type │ basic, cors, error, opaque │
│ response.redirected │ Whether response is redirected │
│ │ │
│ Body Methods (return Promises): │
│ ────────────────────────────── │
│ response.json() │ Parse as JSON │
│ response.text() │ Parse as text string │
│ response.blob() │ Parse as binary Blob │
│ response.arrayBuffer()│ Parse as ArrayBuffer │
│ response.formData() │ Parse as FormData │
│ │
│ ⚠️ Body can only be read ONCE! │
│ │
└─────────────────────────────────────────────────────────────────┘
Common Content Types
┌────────────────────────────────────────────────────────────────┐
│ Content-Type Headers │
├────────────────────────────────────────────────────────────────┤
│ │
│ application/json │ JSON data │
│ application/x-www-form-urlencoded │ Form data (default) │
│ multipart/form-data │ File uploads │
│ text/plain │ Plain text │
│ text/html │ HTML content │
│ application/octet-stream │ Binary data │
│ │
└────────────────────────────────────────────────────────────────┘
Error Handling
┌─────────────────────────────────────────────────────────────────┐
│ Fetch Error Handling │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ⚠️ IMPORTANT: Fetch only rejects on network errors! │
│ │
│ HTTP 404 or 500 → Promise RESOLVES (response.ok = false) │
│ Network failure → Promise REJECTS │
│ │
│ Correct Error Handling: │
│ ────────────────────── │
│ async function fetchWithErrorHandling(url) { │
│ const response = await fetch(url); │
│ │
│ if (!response.ok) { │
│ throw new Error(`HTTP ${response.status}`); │
│ } │
│ │
│ return response.json(); │
│ } │
│ │
└─────────────────────────────────────────────────────────────────┘
Request/Response Headers
// Creating headers
const headers = new Headers();
headers.append('Content-Type', 'application/json');
headers.append('Authorization', 'Bearer token');
// Or as object
const headers2 = new Headers({
'Content-Type': 'application/json',
});
// Headers methods
headers.get('Content-Type'); // Get value
headers.has('Authorization'); // Check existence
headers.set('X-Custom', 'value'); // Set value
headers.delete('X-Custom'); // Delete header
headers.entries(); // Iterator
AbortController - Canceling Requests
┌─────────────────────────────────────────────────────────────────┐
│ Request Cancellation │
├─────────────────────────────────────────────────────────────────┤
│ │
│ const controller = new AbortController(); │
│ const { signal } = controller; │
│ │
│ fetch(url, { signal }) │
│ .then(response => response.json()) │
│ .catch(err => { │
│ if (err.name === 'AbortError') { │
│ console.log('Request cancelled'); │
│ } │
│ }); │
│ │
│ // Later, to cancel: │
│ controller.abort(); │
│ │
│ // With timeout: │
│ const timeoutId = setTimeout(() => controller.abort(), 5000); │
│ │
└─────────────────────────────────────────────────────────────────┘
Common Request Patterns
GET with Query Parameters
const params = new URLSearchParams({
page: 1,
limit: 10,
search: 'javascript',
});
fetch(`https://api.example.com/items?${params}`).then((response) =>
response.json()
);
POST with JSON
fetch('https://api.example.com/users', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'John',
email: 'john@example.com',
}),
});
File Upload
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('description', 'My file');
fetch('https://api.example.com/upload', {
method: 'POST',
body: formData,
// Don't set Content-Type - browser sets it with boundary
});
CORS (Cross-Origin Resource Sharing)
┌─────────────────────────────────────────────────────────────────┐
│ CORS Overview │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Same-Origin: scheme + host + port must match │
│ ──────────────────────────────────────────── │
│ http://example.com/page1 │
│ http://example.com/page2 ← Same origin ✓ │
│ https://example.com/page1 ← Different scheme ✗ │
│ http://api.example.com ← Different host ✗ │
│ http://example.com:8080 ← Different port ✗ │
│ │
│ CORS Headers (Server Response): │
│ ────────────────────────────── │
│ Access-Control-Allow-Origin: * │
│ Access-Control-Allow-Methods: GET, POST, PUT │
│ Access-Control-Allow-Headers: Content-Type, Authorization │
│ Access-Control-Allow-Credentials: true │
│ │
│ Preflight Request (OPTIONS): │
│ ──────────────────────────── │
│ Sent automatically for: │
│ • Non-simple methods (PUT, DELETE, PATCH) │
│ • Custom headers │
│ • Content-Type other than form-urlencoded, multipart, text │
│ │
└─────────────────────────────────────────────────────────────────┘
Credentials and Cookies
// Include cookies in same-origin requests
fetch(url, { credentials: 'same-origin' });
// Include cookies in cross-origin requests
fetch(url, { credentials: 'include' });
// Never include cookies
fetch(url, { credentials: 'omit' });
Retry Logic
async function fetchWithRetry(url, options = {}, retries = 3, delay = 1000) {
for (let i = 0; i < retries; i++) {
try {
const response = await fetch(url, options);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return response;
} catch (error) {
if (i === retries - 1) throw error;
await new Promise((r) => setTimeout(r, delay * Math.pow(2, i)));
}
}
}
Streaming Responses
┌─────────────────────────────────────────────────────────────────┐
│ Response Streaming │
├─────────────────────────────────────────────────────────────────┤
│ │
│ async function* streamResponse(response) { │
│ const reader = response.body.getReader(); │
│ const decoder = new TextDecoder(); │
│ │
│ while (true) { │
│ const { done, value } = await reader.read(); │
│ if (done) break; │
│ yield decoder.decode(value, { stream: true }); │
│ } │
│ } │
│ │
│ // Usage │
│ const response = await fetch(url); │
│ for await (const chunk of streamResponse(response)) { │
│ console.log('Received:', chunk); │
│ } │
│ │
└─────────────────────────────────────────────────────────────────┘
Best Practices
- •Always check response.ok - HTTP errors don't reject the Promise
- •Use AbortController for timeout and cancellation
- •Handle errors properly - network failures and HTTP errors
- •Set appropriate Content-Type - especially for POST/PUT
- •Use async/await for cleaner code
- •Consider retry logic for unreliable networks
- •Don't forget CORS when dealing with external APIs
Common Gotchas
┌─────────────────────────────────────────────────────────────────┐
│ Common Mistakes │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ❌ fetch(url).then(data => ...) │
│ ✓ fetch(url).then(res => res.json()).then(data => ...) │
│ (Response is not the data itself!) │
│ │
│ ❌ Assuming 404 will throw an error │
│ ✓ Check response.ok before processing │
│ │
│ ❌ Reading body twice │
│ ✓ Clone response if you need to read it multiple times │
│ const clone = response.clone(); │
│ │
│ ❌ Setting Content-Type for FormData │
│ ✓ Let browser set it (includes boundary for multipart) │
│ │
│ ❌ Forgetting await with async functions │
│ ✓ Always await fetch and body methods │
│ │
└─────────────────────────────────────────────────────────────────┘
Browser Support
The Fetch API is supported in all modern browsers. For older browsers, use a polyfill like whatwg-fetch or node-fetch for Node.js environments.
Key Takeaways
- •Fetch is Promise-based and supports async/await
- •Check
response.okfor HTTP errors - •Body methods return Promises and can only be called once
- •Use AbortController for request cancellation
- •CORS restrictions apply to cross-origin requests
- •Proper error handling requires checking both network and HTTP errors