Sebagian besar aplikasi web modern berkomunikasi dengan server sepanjang waktu. JavaScript Fetch API adalah cara standar untuk melakukan hal itu, dan sudah terpasang di browser dan di Node.js 18 dan yang lebih baru, jadi tidak ada yang perlu diinstal.

Penggunaan dasar membutuhkan dua baris, namun banyak tutorial berhenti di situ dan mengabaikan bagian yang menyebabkan bug sebenarnya: penanganan kegagalan. Kami menguji contoh dalam panduan ini terhadap server lokal kecil di Node.js 24, dan output yang ditampilkan berasal dari proses tersebut. example.com dalam kode adalah singkatan dari API Anda sendiri. Jika janji merupakan hal baru bagi Anda, mulailah dengan penjelasan janji JavaScript.

Apa itu Ambil API?

Fetch adalah antarmuka berbasis janji untuk membuat permintaan HTTP. Ini menggantikan yang lama, berbasis panggilan balik XMLHttpRequest, dan banyak proyek sekarang menggunakannya daripada menambahkan perpustakaan untuk panggilan sederhana.

Permintaan DAPATKAN

Fetch membuat permintaan GET secara default. Ada dua langkah, dan masing-masing langkah memerlukan await: pertama header respons tiba, lalu Anda membaca isi.

const response = await fetch("https://example.com/users/1");
const user = await response.json();

console.log(user);

// { id: 1, name: 'Asha' }

Kedua langkah tersebut ada karena badannya mungkin besar dan tiba lebih lambat dari header. Dalam skrip browser, await tingkat atas memerlukan modul, jadi Anda biasanya akan memasukkannya ke dalam fungsi async. Lihat panduan async/tunggu JavaScript kami.

Objek Respon

Sebelum Anda membaca isi isi, Anda dapat memeriksa tanggapannya:

console.log(response.status, response.ok, response.headers.get("content-type"));

// 200 true application/json

Tubuh hanya dapat dibaca satu kali. Memanggil json() untuk kedua kalinya gagal dalam pengujian kami:

await res.json();
await res.json();

// TypeError: Body is unusable: Body has already been read

Jika Anda perlu membacanya dua kali, panggil response.clone() terlebih dahulu.

Kejutan besarnya: 404 tidak bisa dilempar

Ini adalah hal terpenting dalam artikel ini. Kami meminta pengguna yang tidak ada:

const res = await fetch("https://example.com/users/999");
console.log(res.status, res.ok);

// 404 false

Tidak terkecuali dilempar. Sejauh menyangkut pengambilan, permintaan berhasil: server telah dijangkau dan dijawab. Janji tersebut ditolak hanya ketika tidak ada respons yang dapat digunakan sama sekali, seperti kegagalan jaringan. Jadi kode seperti ini memiliki bug tersembunyi:

try {
  const res = await fetch(url);
  const data = await res.json();   // may be an error payload
  showUser(data);                  // runs anyway for 404 and 500
} catch (error) {
  showError();                     // does not run for 404 or 500
}

Periksa lembar contekan kode status HTTP kami untuk mengetahui arti setiap kode.

Pembantu yang dapat digunakan kembali

Jangan ulangi pemeriksaan itu di mana pun. Bungkus sekali:

async function getJson(url, options) {
  const response = await fetch(url, options);
  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }
  return response.json();
}

try {
  await getJson("https://example.com/users/999");
} catch (error) {
  console.log("caught:", error.message);
}

// caught: Request failed with status 404

Sekarang kesalahan HTTP dan kesalahan jaringan keduanya berakhir di tempat yang sama catch. Fungsi kecil ini layak dimiliki di setiap proyek. Versi sebenarnya mungkin juga membaca pesan kesalahan dari isi respons, dan menangani respons 204 No Content, yang tidak memiliki JSON untuk diurai.

POST data JSON

Berikan objek opsi sebagai argumen kedua. Untuk JSON, Anda harus melakukan dua hal sendiri: mengonversi data menjadi string dan menyetel header.

const created = await getJson("https://example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Ben" }),
});

console.log(created);

// { id: 2, name: 'Ben', type: 'application/json' }

Server pengujian kami mengulangi jenis konten yang diterimanya, mengonfirmasi bahwa header telah tiba. Lupa bahwa header adalah penyebab umum kesalahan server yang membingungkan, karena banyak kerangka kerja hanya mengurai JSON ketika dideklarasikan. Untuk mengunggah formulir atau file, teruskan objek FormData sebagai isi, dan jangan jangan setel Content-Type, karena browser perlu menambahkan nilai batas itu sendiri.

Metode dan opsi lain

Memilih antara REST dan gaya API lainnya? Perbandingan kami mengenai REST vs GraphQL menunjukkan bagaimana pengambilan cocok dengan masing-masingnya.

String kueri

Jangan membuat string kueri dengan menggabungkan teks, karena karakter khusus akan merusaknya. URLSearchParams menangani pengkodean untuk Anda:

const params = new URLSearchParams({ q: "red shoes", page: 2 });
console.log(params.toString());

// q=red+shoes&page=2

await getJson(`https://example.com/search?${params}`);

// { q: 'red shoes', page: '2' }

Server menerima red shoes dengan benar, dengan ruang dipulihkan.

Batas waktu dan pembatalan

Pengambilan akan menunggu lama di server yang lambat kecuali Anda memberitahukannya sebaliknya. AbortSignal.timeout() menetapkan batas. Titik akhir pengujian kami memerlukan waktu dua detik, dibandingkan batas 200 milidetik:

try {
  await fetch("https://example.com/slow", { signal: AbortSignal.timeout(200) });
} catch (error) {
  console.log(error.name);
}

// TimeoutError

Untuk membatalkan secara manual, misalnya saat pengguna meninggalkan halaman atau mengetikkan istilah pencarian baru, gunakan AbortController:

const controller = new AbortController();
const pending = fetch("https://example.com/slow", { signal: controller.signal });

controller.abort();

try {
  await pending;
} catch (error) {
  console.log(error.name);
}

// AbortError

Untuk menjalankan beberapa permintaan sekaligus, gunakan Promise.all, yang jauh lebih cepat daripada menunggunya satu per satu:

const [user, search] = await Promise.all([
  getJson("https://example.com/users/1"),
  getJson("https://example.com/search?q=a&page=1"),
]);

Setiap jenis kegagalan

Berikut tampilan setiap kegagalan yang kami jalankan, beserta cara membedakannya:

Baris terakhir itu biasa terjadi dalam produksi. Proksi yang mengembalikan 502 sering kali mengirimkan halaman kesalahan HTML. Kami mereproduksi ini, dan res.json() melemparkan SyntaxError. Memeriksa response.ok sebelum penguraian berarti Anda melaporkan masalah sebenarnya, bukan kesalahan penguraian yang membingungkan.

CORS dan kredensial

Di browser, permintaan dari satu asal ke asal lainnya tunduk pada CORS, aturan berbagi sumber daya lintas asal. Jika Anda melihat kesalahan yang menyebutkan Access-Control-Allow-Origin, perbaikan ada di server, yang harus mengizinkan situs Anda. Di JavaScript Anda, kegagalan hanya muncul secara umum TypeError, jadi lihat konsol browser untuk mengetahui alasan sebenarnya. Node.js tidak menerapkan CORS, jadi permintaan yang berfungsi dalam skrip masih bisa gagal di browser.

Secara default, browser tidak mengirimkan cookie pada permintaan lintas asal. Atur credentials: "include" jika Anda membutuhkannya, dan pastikan server mengizinkannya. Jangan pernah menaruh kunci API rahasia di browser JavaScript, karena siapa pun dapat membacanya. Simpan di server Anda.

Kesalahan umum

• Tidak memeriksa response.ok. Respons kesalahan dianggap berhasil.
• Melupakan yang kedua await. response.json() juga mengembalikan janji.
• Lupa JSON.stringify. Melewati suatu objek saat tubuh mengirimkan [object Object].
• Mengatur Content-Type dengan FormData. Ini melanggar batas, jadi tinggalkan saja.
• Tidak ada batas waktu. Permintaan yang digantung dapat membuat pemintal halaman berjalan tanpa batas waktu.
• Mengurai JSON untuk respons kosong. A 204 tidak memiliki isi, dan json() akan dilempar.

Penutup

Pengambilan itu sederhana setelah Anda mengingat aturan utamanya: respons tidak sama dengan kesuksesan. Salin pembantu kecil ke dalam proyek Anda, tambahkan batas waktu dan uji jalur kegagalan Anda. Sebagai langkah selanjutnya, buat halaman kecil yang memuat data dari API, menampilkan pesan kesalahan yang jelas, dan memungkinkan pengguna membatalkan pencarian yang lambat.

Pertanyaan yang sering diajukan

Teruslah belajar