Lewati ke konten utamaSkip to content
TG
Taqiyya Ghazi
Kembali ke semua tulisanBack to all articles
4 menit baca

response.data atau response.result? Mengapa API yang Tidak Konsisten Menghambat Tim Frontend

#web-development#software-engineering#api-design#javascript#best-practices

Pelajaran berharga yang saya dapat dengan cara sulit: Prediktabilitas adalah fitur terbaik dari sebuah API.

Ketika memulai karier sebagai Junior Developer di sebuah proyek legacy, saya punya pola pikir yang sangat sederhana soal API: “Selama endpoint mengembalikan data yang benar, tugas saya selesai.”

Saya tidak peduli pada strukturnya. Saya tidak peduli pada standarisasi key. Jika hari ini ingin menamai properti kembalian result, saya pakai itu. Jika besok ingin memakai data, saya pakai itu juga.

Awalnya terlihat sepele. Namun seiring tim berkembang dan saya mulai mengerjakan fitur yang mengintegrasikan banyak layanan sekaligus, saya sadar telah menciptakan masalah besar.

Berikut alasan mengapa respons API yang tidak konsisten menjadi pembunuh produktivitas secara diam-diam, dan bagaimana kami memperbaikinya.

“Wild West” di Kode Legacy

Masalahnya mencuat saat integrasi fitur besar. Saya bekerja bersama seorang Frontend Developer yang tampak benar-benar frustrasi.

“Bro,” tanyanya, “Untuk profil user, datanya ada di response.data, response.result, atau langsung di root responsnya?”

Saya terdiam. Sejujurnya saya tidak tahu. Saya harus membuka kode untuk mengeceknya.

Kami menelusuri codebase dan menemukan campuran gaya yang kacau:

  • Perang Wrapper: Beberapa endpoint mengembalikan { data: ... }, sebagian lain { result: ... }, dan sisanya tanpa wrapper sama sekali.
  • Benturan Penulisan (Casing): Developer berlatar Python memakai user_id (snake_case), sementara developer JavaScript memakai userId (camelCase).
  • Lotre Error: Sebagian error mengembalikan status 400 dengan pesan JSON; sebagian lain mengembalikan 200 OK tetapi berisi string { status: "error" }.

Biaya dari Ketidakkonsistenan

Pendekatan “Wild West” ini bukan sekadar terlihat berantakan; ada biaya nyatanya:

  • Kode Frontend Membengkak: Tim frontend tidak bisa membuat HTTP handler yang reusable. Mereka harus menulis logika parsing khusus untuk setiap endpoint.
  • Mimpi Buruk Maintenance: Setiap kali kami melakukan refactor, selalu ada bagian yang rusak karena struktur datanya tidak bisa diprediksi.
  • Kelelahan Mental: Setiap kali membuat API baru, kami membuang waktu berdebat soal struktur alih-alih mengikuti satu standar.

Saya pun sadar bahwa di dalam tim, gaya coding pribadi Anda jauh kalah penting dibandingkan konsistensi tim.

Solusinya: Standar “Minimalis”

Ketika akhirnya kami memutuskan me-refactor kode legacy, hal pertama yang kami bahas adalah API Contract.

Kami tidak hanya menginginkan konsistensi, tetapi juga efisiensi. Mengirim data redundan (seperti "success": true atau kalimat pesan panjang) di setiap respons adalah pemborosan bandwidth.

Jadi, kami menetapkan aturan tegas: Biarkan HTTP Headers menangani status, dan biarkan Body menangani konteks.

Berikut kontrak yang kami sepakati:

Respons Sukses

Jika pemanggilan API berhasil, kami mengembalikan kode status HTTP 2xx. Untuk body, kami membungkus kontennya secara ketat di dalam key data. Kami tidak mengirim string pesan (misalnya "Data loaded successfully") karena hanya memakan bandwidth. Jika datanya tiba, UI sudah tahu apa yang harus dilakukan.

  • Format:
// HTTP Status: 200 OK
{
  "data": {
    "id": 101,
    "fullName": "John Doe",
    "email": "john@example.com"
  }
}

Respons Error

Jika pemanggilan API gagal, kami mengembalikan kode status HTTP 4xx atau 5xx. Untuk body, kami hanya mengembalikan kode error. Kami tidak mengirim pesan error yang dibaca manusia dari backend. Mengapa? Dua alasan:

  • Bandwidth: Mengirim "INVALID_CREDENTIALS" jauh lebih ringan daripada mengirim "The username or password you entered is incorrect."
  • Lokalisasi: Frontend seharusnya bertanggung jawab menerjemahkan error. Dengan mengirim kode, Frontend dapat memetakan INVALID_CREDENTIALS ke "Wrong Password" (Inggris) atau "Password Salah" (Indonesia) tanpa menyentuh Backend.
// HTTP Status: 401 Unauthorized
{
  "code": "INVALID_CREDENTIALS"
}

Aturan Penulisan Key

Kami sepakat mewajibkan camelCase secara ketat untuk seluruh properti JSON, terlepas dari apakah backend ditulis dengan Python atau Node.js.

Dampaknya: Kecepatan Pengembangan

Dampak standarisasi ini terasa seketika.

Untuk Tim Backend: Kami berhenti membuang waktu memperdebatkan nama variabel. Kami tinggal mengikuti template, dan code review fokus pada logika bisnis, bukan semantik penamaan.

Untuk Tim Frontend: Ini kemenangan terbesar. Karena strukturnya dapat diprediksi dan minimalis, mereka bisa menulis Global Interceptor (menggunakan Axios atau Fetch) untuk menangani seluruh respons secara terpusat.

// Contoh Global Interceptor
axios.interceptors.response.use(
  (response) => {
    // Sukses: Kami PASTI tahu kontennya selalu di response.data.data
    return response.data.data; 
  },
  (error) => {
    // Error: Kami ambil KODE-nya dan terjemahkan di sisi klien
    const errorCode = error.response.data.code;
    
    // Memetakan kode ke bahasa yang ramah pengguna
    const userMessage = getTranslation(errorCode); 
    
    Notification.error(userMessage); 
    return Promise.reject(error);
  }
);

Penutup

Seiring tim Anda bertumbuh, konsistensi menjadi jauh lebih penting daripada kesempurnaan.

Tidak masalah apakah Anda memilih snake_case atau camelCase. Yang terpenting adalah seluruh anggota tim mengikuti aturan yang sama.

Me-refactor respons API kami bukan hanya merapikan kode, melainkan juga memperbaiki komunikasi tim. Kami berhenti menebak-nebak nama key dan kembali fokus membangun fitur.

Jika Anda seorang Junior Dev atau bekerja di tim yang sedang bertumbuh, tetapkan aturan respons API sejak dini. Diri Anda di masa depan (dan tim frontend Anda) akan sangat berterima kasih.