Periksa kontrak sebelum menulis client

Integrasi client JavaScript dengan birds.cafe harus dimulai dari kontrak yang benar-benar dinyatakan repositori, bukan dari tebakan berdasarkan nama domain. Jangan menganggap situs tersebut menyediakan endpoint publik, format respons, atau autentikasi tertentu sebelum menemukan dokumentasi atau implementasi yang membuktikannya.

Referensi repositori: github.com/kanavtwtgg/birds.cafe. Untuk memeriksa batas integrasi, klon repositori dan cari dokumentasi, konfigurasi URL, pemanggilan jaringan, serta rute server:

git clone https://github.com/kanavtwtgg/birds.cafe.git
cd birds.cafe
find . -maxdepth 3 -type f | sort
grep -RInE 'fetch\(|axios|baseURL|https?://|/api/|router\.|app\.(get|post|put|delete)' . --exclude-dir=node_modules --exclude-dir=.git

Periksa pula berkas README, spesifikasi OpenAPI, file konfigurasi, dan kode server jika tersedia. Bedakan URL untuk aset atau halaman web dari endpoint API. Jika repositori tidak mendokumentasikan atau mengimplementasikan API eksternal, simpulkan bahwa kontrak tersebut belum dapat dipastikan; jangan membuat endpoint sendiri lalu menyebutnya sebagai API birds.cafe.

Catat bukti kontrak

Sebelum mengintegrasikan, catat metode HTTP, URL, kebutuhan autentikasi, header, bentuk request, bentuk response, dan arti kode status. Cantumkan lokasi bukti, misalnya nama berkas dan bagian dokumentasi. Jika satu unsur tidak ditemukan, tandai sebagai belum diketahui dan minta konfirmasi pemilik layanan.

Validasi request dan response

Validasi request membantu mencegah client mengirim nilai di luar kontrak. Validasi response membantu mendeteksi perubahan atau respons yang tidak sesuai sebelum data dipakai aplikasi. Validasi di client bukan pengganti validasi server: server tetap harus memeriksa input karena client dapat dimodifikasi atau dilewati.

Contoh berikut bersifat ilustratif. Fungsi menerima URL, metode, dan pemeriksa respons dari pemanggil; nilai tersebut harus berasal dari kontrak terverifikasi. Pemeriksa di bawah hanya contoh lokal, bukan skema birds.cafe.

async function requestJson(url, { method = "GET", body, validate } = {}) {
  const response = await fetch(url, {
    method,
    headers: body === undefined ? {} : { "Content-Type": "application/json" },
    body: body === undefined ? undefined : JSON.stringify(body),
    signal: AbortSignal.timeout(5_000),
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }

  const contentType = response.headers.get("content-type") ?? "";
  if (!contentType.includes("application/json")) {
    throw new Error("Respons bukan JSON");
  }

  const data = await response.json();
  if (!validate(data)) {
    throw new Error("Bentuk respons tidak sesuai kontrak");
  }
  return data;
}

// Validator ini hanya contoh ilustratif, bukan skema birds.cafe.
const isExampleResponse = (value) =>
  value !== null &&
  typeof value === "object" &&
  typeof value.id === "string";

AbortSignal.timeout membatasi waktu tunggu pada runtime yang mendukungnya. Jika target runtime tidak mendukung API tersebut, gunakan mekanisme pembatalan yang tersedia di runtime itu. Jangan menerima respons JSON hanya karena parsing berhasil: periksa tipe konten dan validasi field yang memang diwajibkan kontrak.

Timeout, retry, dan perubahan kontrak

Timeout mencegah permintaan menggantung tanpa batas. Retry tidak selalu aman: mengulang operasi baca biasanya tidak mengubah data, tetapi mengulang operasi tulis dapat membuat perubahan ganda jika server sudah memproses permintaan pertama sebelum koneksi terputus.

  • Mulai dengan tanpa retry otomatis sampai metode, efek samping, dan perilaku kode status dipahami.
  • Untuk operasi yang aman diulang, retry hanya pada kegagalan sementara yang sesuai kebijakan layanan. Batasi jumlah percobaan dan gunakan jeda bertambah; hormati Retry-After jika kontrak menetapkannya.
  • Untuk operasi tulis, retry hanya jika API menyediakan jaminan idempotensi yang terdokumentasi, seperti kunci idempotensi. Jangan mengarang header tersebut.
  • Jangan retry kesalahan validasi atau autentikasi tanpa memperbaiki penyebabnya.

Ketika kontrak berubah, perbarui validator dan pengujian bersama perubahan integrasi. Perubahan field wajib, tipe data, metode, atau autentikasi dapat mematahkan client meskipun respons masih berupa JSON. Jika server menyediakan versi atau spesifikasi kontrak, gunakan sumber tersebut sebagai acuan; jangan menyimpulkan kompatibilitas hanya dari satu respons yang berhasil.

Uji dengan mock dan integrasi

Mock untuk perilaku client

Mock cocok untuk menguji logika client tanpa bergantung pada jaringan atau layanan eksternal. Verifikasi bahwa client menangani respons sukses, status HTTP gagal, JSON tidak valid, bentuk respons yang salah, dan timeout. Mock hanya membuktikan perilaku terhadap skenario yang Anda tulis; mock tidak membuktikan bahwa endpoint sungguhan atau skema tersebut ada.

Pengujian integrasi untuk kontrak nyata

Pengujian integrasi harus menggunakan endpoint dan kredensial yang memang dinyatakan oleh dokumentasi atau pemilik layanan. Jalankan secara terpisah dari pengujian unit, gunakan data yang aman, dan hindari operasi yang mengubah data produksi. Jika repositori tidak menyediakan API eksternal yang dapat dipastikan, jangan membuat tes jaringan ke URL hasil tebakan. Minta endpoint uji atau spesifikasi resmi terlebih dahulu.

Untuk memudahkan diagnosis, catat metode, status, dan konteks kegagalan tanpa mencatat token, rahasia, atau isi sensitif. Saat uji gagal, periksa apakah kegagalan berasal dari jaringan, status HTTP, parsing, atau validasi skema; masing-masing menunjukkan masalah berbeda.

Checklist integrasi

  1. Temukan bukti endpoint dan skema di dokumentasi atau implementasi repositori.
  2. Pastikan metode, autentikasi, header, dan perilaku error sebelum mengirim request.
  3. Validasi input pada batas client dan validasi respons sebelum dipakai.
  4. Tetapkan timeout; aktifkan retry hanya untuk operasi dan kondisi yang aman.
  5. Uji perilaku dengan mock, lalu uji integrasi hanya terhadap layanan yang terverifikasi.

Jika pemeriksaan repositori tidak menemukan kontrak API, langkah yang tepat adalah mengonfirmasi batas integrasi kepada pemilik birds.cafe. Contoh kode generik dapat membantu menyiapkan client, tetapi tidak boleh diperlakukan sebagai bukti adanya API.